@troylar/sightline 0.0.0-stage → 1.120.3

package/docs/roadmap.md

@@ -0,0 +1,232 @@
+# Roadmap: building vision.md
+
+This is the historical implementation sequence, not the current feature status or a delivery commitment.
+For today's product, start with [the visual guide](../README.md) and [release history](../CHANGELOG.md).
+
+The plan for building [vision.md](https://github.com/troylar/sightline-planner/blob/main/vision.md), release by release. Each release is one PR with its own tests.
+Function names are given instead of line numbers, because lines move.
+
+## What the code tells us first
+
+- **The plan file cap is 2 MB** (`MAX_BYTES`, checked in `parseText` and `readFile`). The 5 MB cap is for the Jira
+  status file. Everything added to the plan (who added what, tags, the change log) has to fit.
+- **Older copies of the page delete fields they don't know.** `normalize` rebuilds every item from a list of known
+  fields, so an older page that saves drops everything new. The foundation release (below) has to come before any new
+  saved field.
+- **Notes already have `created` as a string**, so "who added it" can't use that name. It's `added: {by, at}`.
+- **`commit` runs on every keystroke** (text fields commit as you type, grouped by `coalesce`). Anything it does each
+  time must be cheap.
+- **A merge treats a field changed on both sides as a clash.** An "edited by" stamp would clash on every shared item,
+  so it must be exempt.
+- **`applyJira` writes Jira's status and dates into the plan on every draw.** This goes against "shown, not copied",
+  and those writes must never be counted as someone's edit.
+
+## Releases
+
+Status (2026-09-27): 1.17–1.24 built as PRs #21–#28, the safety release as 1.25 (#29), and proposed changes (step 7)
+as 1.26 (#30). Step 8 started with the standup board as 1.27. The retrospective and canvas views, and write-back
+(step 9), need decisions first.
+
+| Release | What | Needs |
+|---|---|---|
+| 1.17.0 | **From Jira vs Added here at a glance:** two looks, legend, sprint headers, counts with units, layers (Everyone / Jira only), hidden counts | none |
+| 1.18.0 | **Jira facts shown, not copied:** titles and assignees follow Jira; chart label and lead are the plan's; Jira sprint names read-only | 1.17 |
+| 1.19.0 | **Foundation:** one storage interface, schema migrations, protection against older pages dropping new fields, read cap raised to 5 MB | none; must come before 1.20 |
+| 1.20.0 | **Who added what, and the change log:** stamps on everything, Activity list, note author locked, Mine layer | 1.19, 1.17 |
+| 1.21.0 | **Hide by person:** Added-by filter, hide someone's items, hidden counts by reason, links to hidden items, undo one change | 1.20 |
+| 1.22.0 | **Tags:** plan tags on everything (Jira items too, by key); Jira labels from the sync, read-only | 1.20, 1.17 |
+| 1.23.0 | **Cards in two parts:** From Jira (read-only), then Added here | 1.18, 1.20, 1.22 |
+| 1.24.0 | **Notes and dependencies on Jira items**, attached by Jira key | 1.18, 1.23 |
+
+1.17 and 1.19 can ship in either order; 1.18 can follow 1.17 directly. "Mine" comes with 1.20, once there's a record of
+who added what.
+
+## 1.17.0: From Jira vs Added here
+
+- **Which side:** `sideOf(item)` returns "jira" for stories, Jira-linked tasks, Jira-linked leaf initiatives and epic
+  initiatives, and "plan" for everything else.
+- **Look:**
+  - Jira items: surface fill, 2px workstream-color outline, a mono key chip (the first epic key, "+n" for more).
+  - Plan items: filled, as today, with a slot for the author's initials (drawn from 1.20).
+  - Stories switch from dashed to the Jira look. Dashed stays only for "outside the plan's dates".
+- **Sprint headers:** Jira sprints get a "Jira" chip, with Jira's exact dates in the hover ("drawn in whole weeks").
+  The plan's own timeboxes look like plan items.
+- **Legend:** From Jira, Added here, Jira sprint, plan timebox.
+- **Counts:** `5/9 stories`, `2/5 tasks`, `3/4 items`, with "(partial)" when counting stopped early. The weighted %
+  moves to the hover card, and the progress fill follows the count.
+- **Layers:**
+  - Everyone or Jira only, saved per viewer and per plan in localStorage; team views can save a layer too.
+  - Applied in every visibility function: bars, tasks, milestones, gates, notes, meetings, blocks.
+- **Hidden counts:** a slim line under the view bar, not a warning. For example: "12 plan items hidden by your layer
+  · Show everyone", "2 parked", "Notes hidden (N)".
+- **Tests (each fails on 1.16.1):** Jira vs plan classes and key chips in Weeks and Days; sprint header classes; the
+  legend; no bare `%` tags; the Jira-only layer hides a hand-made bar and counts it; the layer is per plan; parked
+  items are counted.
+
+## 1.18.0: Jira facts shown, not copied
+
+- **Title:** `titleOf(item)` gives Jira's summary when the Jira files have it. Otherwise it gives the stored label or
+  key, marked stale ("Jira files not loaded"). `chartLabel` becomes the chart label, else `titleOf`. Every place the
+  page draws a label switches to it: chart, card, hover, Find, Today, warnings.
+- **Adding from Jira stops copying.** `epicOnNew`, `batchOn` and `addFromJira` store the key as the label and no
+  owners or status.
+- **Assignee and lead, worked out when the page draws (no file change):**
+  - The assignee comes from Jira.
+  - The `owners` field stays in the file but is labeled **Lead (plan)** on Jira items. An owners list equal to the
+    assignee counts as the old copy, so no lead.
+  - The people filter, people rows, Today and load use assignee plus lead.
+- **Titles that differ from Jira:** there's no automatic rewrite, since a teammate's rename can't be told apart from a
+  Jira rename. Plan, then Epics lists them with two choices: **Keep ours as the chart label**, or **Use Jira's**. The
+  chart label cap goes to 60 characters.
+- **Sprints:** the name and goal of a Jira sprint come from Jira and are read-only; its weeks stay the plan's.
+- **Tests:** a stale stored title appears nowhere once Jira has the real one; the stale mark shows without Jira;
+  nothing is copied on add; the assignee counts for the people filter; the Jira sprint name is read-only; "keep ours"
+  sets the chart label.
+
+## 1.19.0: Foundation
+
+- **Storage interface:**
+  - `store.load()`, `store.apply(change)`, `store.save(plan)`, `store.lock()`, `store.subscribe(cb)`, `store.draft`.
+  - Backends: `FileStore` (the shared file) and `LocalStore` (this browser only).
+  - Moves in: reading and writing the file, the quick-update read–apply–write–retry core, verify-later, polling for
+    changes, the local draft.
+  - Merging becomes a pure `mergePlans(base, mine, theirs)`; the page keeps backups and messages.
+  - Save stays a whole-file write in this release.
+  - A later database backend implements the same interface.
+- **Schema:** `meta.schema` with an ordered list of migrations, run before `normalize`. Only a change older pages can't
+  read bumps it. New optional fields go in `meta.features` instead.
+- **Protection against older pages:**
+  - `meta.features` and `meta.savedWith` mark what's in the file.
+  - A page that finds a feature it doesn't know, or a newer schema, opens the plan read-only, with no quick updates:
+    "Saved by a newer Sightline. Update this copy to edit."
+  - A save by a page older than 1.19 is detected (it drops `savedWith`), with an offer to put back what it removed.
+- **Size:** the read cap goes to 5 MB; the write cap stays at 2 MB until older copies are gone. Undo history is capped
+  by size (it holds whole-plan snapshots).
+- **Proof:** a pure refactor, so every existing test passes unchanged. New tests cover a file changing mid-save,
+  subscribe firing once per change, the merge matching the old one, and the read-only and put-back paths.
+
+## 1.20.0: Who added what, and the change log
+
+- **Stamps:** `added: {by, at}` and `edited: {by, at}` on every plan item, stamped in one place in `commit`:
+  - New ids get `added`; changed items get `edited`.
+  - Stamping happens after the edit, before `reschedule` and `applyJira`, so an item moved automatically isn't counted
+    as your edit.
+  - `added` never changes in a merge; `edited` takes the later one and never counts as a clash.
+  - Old items show "not recorded". Notes take theirs from the existing author.
+- **Change log:**
+  - `S.changes`, entries `{id, by, at, what, ops}`: one per quick update, one per Save. The log never includes itself,
+    or Jira's own values that `applyJira` wrote.
+  - Kept to the smaller of 1,000 entries, 30 days and 256 KB; entries over 16 KB keep a summary only.
+  - Entries are only ever added, so they merge safely. It's advice, not an audit: a shared file can't prove who did
+    what.
+- **Screens:**
+  - "Added by Avery Stone, Sep 27 · edited by Blake, Sep 28" in cards and hover.
+  - The note author is no longer editable, and editing someone else's note asks first.
+  - A new Plan, then Activity page.
+  - The Mine layer: Jira items plus what I added, with older items counted.
+  - Author initials on plan items.
+- **Size check:** the 100-epic demo plan with stamps must grow by less than 35% and stay under 2 MB.
+
+## 1.21.0: Hide by person
+
+- An "Added by" filter; a per-viewer, per-plan hide list. It never hides Jira items, only what people added on them.
+- Hidden counts by reason ("8 hidden by your view (Avery 5, Blake 3) · Show all").
+- **Links to hidden items:** an item whose dependency is hidden gets a "⇠ 1 hidden" tag that opens it.
+- **Undo one change** from Activity: reverse only the fields that still hold that change's value, and report the rest.
+
+## 1.22.0: Tags
+
+- **Tag definitions:** `S.tags` (id, name, color, stamps).
+- **Tags on plan items:** `tags: [id]`.
+- **Tags on Jira items:** `S.jiraItems`, one entry per key, which is also where later plan notes on Jira items go.
+  Tag lists merge as sets everywhere.
+- **Jira labels:** the sync fetches `labels`. They're shown read-only, marked as Jira's, and kept separate from a plan
+  tag with the same name.
+- **Filters and views:** show only or hide by tag or by label; a tag index is built once per draw.
+- **Screens:** tag chips on bars; a Plan, then Tags page to create, rename, recolor and delete; adding a tag is a quick
+  update anyone can make.
+
+## 1.23.0: Cards in two parts
+
+- **From Jira (read-only):** key, title, status as the team reads it, assignee, sprint and exact dates, points, type,
+  labels, when it was synced, Open in Jira.
+- **Added here:** chart label, lead, placement, at risk and blocked, tags, notes, dependencies, stories switched off,
+  added and edited by.
+- Plan items show only Added here. No inputs inside From Jira.
+
+## 1.24.0: Notes and dependencies on Jira items
+
+- **Notes:**
+  - Notes attach by `jira:KEY` and follow the issue.
+  - A note whose issue isn't in the last sync keeps its place, marked "not in the last sync", and is listed in Epics.
+  - New notes on Jira items attach by key.
+- **Dependencies:**
+  - `dependsOn` accepts `jira:KEY`. Warnings are worked out from Jira's end date (the sprint end, then the due date,
+    else "has no sprint").
+  - Dependencies on Jira items never reschedule anything.
+- **Sync:** the sync also fetches keys named in notes, tags and dependencies, capped.
+
+## Safety: when Jira items go missing
+
+vision.md principle 12. Plan work around a Jira item is never deleted because a sync stopped returning it:
+- **Today:** it already holds. Switched-off stories, parked epics, Jira-linked initiatives and tasks, and epic
+  links are all kept by key in the plan, and nothing prunes them when a key is missing.
+- **1.24:** notes and tags on Jira items attach by key and are listed under "not in the last sync" rather than
+  dropped. They reattach by themselves when the issue returns. Tests: remove a story from the status file, then
+  bring it back, and check its notes and tags are back on it.
+- **A guard against a bad sync:** when a sync returns far fewer of the plan's Jira items than the last one (for
+  example, more than a third missing, or none at all), the script keeps the previous files and reports the problem
+  instead of replacing them. The page shows "The last sync is missing 40 of this plan's Jira items; showing the
+  earlier sync. Nothing was removed." Built in 1.25 (with `--accept-drop` for a real drop).
+- **Readable while missing:** the page remembers, in the browser only, the last title it saw for each key, so a
+  missing item shows "ABC-12 · Faceted search (not in the last sync)" rather than just its key.
+
+## Later, in outline
+
+- **Proposed changes:**
+  - `S.proposals`, entries `{id, server, key, field, value (by ID), seen {value, at}, why, added, review, applied}`.
+  - Shown as pending on the item, with a list to review. "Landed" when Jira has the value.
+- **Views:**
+  - Standup cards (the current sprint by person) and a retrospective (fed by the change log).
+  - A free-form canvas, storing only positions in `S.canvas`.
+  - All views share `sideOf`, the layers and the hidden counts.
+- **Write-back:**
+  - An `apply` command in the sync script, never the page, using a separate write token.
+  - Per change: refetch, apply only if Jira still has the value the proposal saw, confirm, refetch to check. Results go
+    to a file the page reads.
+  - Only allowed fields can be written. Conflicts, permission errors and ambiguity are skipped and reported.
+- **Flattening tasks out of initiatives:**
+  - Not now. The change engine already treats tasks as flat, and new collections are flat.
+  - A database backend can map to flat tables without changing the file.
+  - If the file must flatten, do it in a 2.0 migration that writes both forms for a release.
+
+## Decisions (recommended)
+
+| | Decision | Recommendation |
+|---|---|---|
+| D1 | How epic initiatives look | The Jira way (outlined, epic key); their plan fields show under Added here |
+| D2 | What Mine means | Jira items plus what I added; ship it with 1.20, not before |
+| D3 | Titles that differ from Jira | No automatic rewrite; show Jira's, offer a review list; chart label up to 60 characters |
+| D4 | Owners on Jira items | Keep `owners` as the plan's lead; the assignee comes from Jira |
+| D5 | Jira files not loaded | Show the stored title or key, marked stale |
+| D6 | Progress fill | By count, matching the label; weighted % in the hover |
+| D7 | Hidden counts | An info line under the view bar, not a warning |
+| D8 | Authors who leave the team | Keep their ids; show "Former teammate" |
+| D9 | Change log size | 1,000 entries, 30 days or 256 KB; advice, not an audit |
+| D10 | File size | Read up to 5 MB from 1.19; write up to 2 MB until older copies are gone |
+| D11 | Who can tag | Anyone, as a quick update; managing tag definitions needs Start editing |
+| D12 | Dependencies on Jira items | Warn only; never reschedule |
+| D13 | Older pages and new features | Open read-only, no quick updates |
+
+## Known conflicts, and when they're fixed
+
+1. **`applyJira` writes Jira's status and dates into the plan** (vision gap 8). From 1.20 those writes are kept out of
+   the change log and never stamped as an edit. They're replaced with draw-time values after 1.24; that's a wide
+   change, because rollups, rescheduling, warnings and Today all read the stored dates.
+2. **Following Jira's sprints copies them into the plan** (gap 7). Names and goals become read-only in 1.18. The copy
+   stays, since the plan's sprints are its time grid.
+3. **Adding from Jira copies status.** Stopped in 1.18.
+4. **Older pages drop unknown fields.** Handled by the 1.19 foundation.
+5. **The note author can be changed.** Locked in 1.20.
+6. **Some view settings are global rather than per plan.** New ones are keyed by plan.
+7. **Undo keeps up to 200 whole-plan snapshots.** Capped by size in 1.19.

package/docs/screenshots.md

@@ -0,0 +1,57 @@
+# Screenshot capture notes
+
+The tour uses actual Sightline 1.94.0 UI, captured in Chromium at 1440 × 850 CSS pixels in light and dark themes.
+All people, projects, issues, outcomes and proposals belong to the invented Northstar example.
+
+## Recreate the source data
+
+From a trusted source checkout:
+
+```sh
+./build.sh
+python3 tools/make-docs-demo.py
+```
+
+The generator writes `demo/plan.json` and `demo/jira/`. It uses current dates for Jira/sprint examples and fixed
+Q4 2026–Q3 2027 roadmap targets. The checked-in `examples/northstar/` is a documentation snapshot, so its Jira
+freshness naturally ages. It also contains two deliberately prepared amendments, not a live AI response.
+
+## Capture the actual screens
+
+Open the built HTML in a clean browser profile, open the synthetic plan, connect its synthetic Jira folder,
+and choose Avery Stone as the example viewer. Keep **This browser only** visible if working with a detached copy.
+Capture:
+
+- Roadmap: Four quarters, starting Q4 2026; the one Later outcome remains outside the window.
+- Timeline: by workstream, in weeks, with the Jira and plan work visible.
+- Today: Team scope, including its freshness and coverage line.
+- Assistant: Roadmap → Plan with AI, with a drafted request and no claimed live response.
+- Review: connect the prepared amendments file; show both Ready changes with Apply, Skip and Edit. Scroll the
+  inspector enough to show those controls without changing their contents.
+
+The documentation capture used browser automation to load only these synthetic files. It does not establish a
+native file-picker permission round trip, live endpoint connectivity, cloud freshness or two-device behavior.
+Don't hide warning/coverage information or edit screenshots to imply a capability the app doesn't have.
+
+Use paired `<picture>` sources in Markdown, describe the relevant action in the alt text, and inspect both images
+before publishing. Keep image filenames stable when refreshing the tour.
+
+The bundled-skills dialog was captured from Sightline 1.96.0 opened from a standalone HTML copy. Its ZIP
+was downloaded through the actual browser UI and compared with the embedded manifest using Python zipfile.
+Direct native folder-picker permissions remain a separate manual check.
+
+## Prepared planning storyboard
+
+`planning-story-*.svg` is an illustration, not a screenshot or model response. Its four variants cover
+wide/narrow layouts and light/dark themes. The content follows `examples/northstar/brain-dump.txt` and
+`roadmap-session-amendments.json`: a Q2-to-Q1 target move plus an unscheduled idea. Its labels explicitly say
+that the proposals are prepared. It makes no capacity or live-connectivity claim. Check all variants when
+changing the example, keep text readable, and retain an accurate text equivalent beside the image.
+
+## Roadmap map and decision brief
+
+`roadmap-map-*.svg` is a conceptual map of the planning workflow, not an app screenshot.
+`planning-decisions-*.svg` illustrates the ten-note exercise in `roadmap-planning-example.md`; its capacity
+numbers belong to one invented Platform sprint, not a delivery forecast. Both sets have wide/mobile and
+light/dark variants. Keep their text equivalents in the image descriptions and the linked worked session.
+SVGs are static, self-contained source artwork with no scripts, external resources, or embedded app UI.

package/docs/skill-evaluation.md

@@ -0,0 +1,71 @@
+# Evaluate the planning skills
+
+**Source-tool availability:** the optional runner below requires a checkout containing
+`test/skill-evals/run.js`. It is not part of public-source 1.94.0 or the installed skill folders.
+Use the acceptance criteria for manual independent review when that runner is absent.
+
+These tasks test an assistant following the installed instructions, separately from the application's
+deterministic regression suite. All plans, people and proposals are synthetic. No endpoint credentials,
+network calls or real assistant folders are needed.
+Run from a trusted source checkout with the development dependencies installed (`npm ci`); the evaluation
+scripts are not part of the standalone app or installed skill folders.
+
+## Run an independent evaluation
+
+Build first, then prepare a **new** temporary directory:
+
+```sh
+./build.sh
+node test/skill-evals/run.js prepare /tmp/sightline-skill-evaluation
+```
+
+Each case contains a self-contained copy of its skill, a request, and synthetic plan/context files. Some
+also contain proposals and results. Preparation refuses an existing directory to avoid reusing old answers.
+An optional final argument to `prepare` selects another skills root for a comparison run. Pass the same skills root to `check` when evaluating that version.
+
+Give an independent file-capable assistant each case's `request.md` and `SKILL.md`, with access only to that
+case and the trusted offline checker identified in the request. Do not supply the acceptance table below
+or prior review conclusions. Have it execute the request and save its user-facing answer as `response.md`.
+For a comparison, use fresh assistant context for each version. A passing old version does not prove the
+instructions have the missing rule; a failed old version is needed to claim a demonstrated regression fix.
+
+Check the resulting files:
+
+```sh
+node test/skill-evals/run.js check /tmp/sightline-skill-evaluation
+```
+
+The checker compares original input hashes, rejects unexpected writes, verifies that the evaluated skill
+still matches the current source, and runs generated proposals through the built app's actual parser
+and amendment checker under jsdom. It also checks the requested stable targets, current-value preconditions, and
+unscheduled idea behavior. Temporary files from a completed atomic write must have been cleaned up.
+
+This command does **not** call a model or grade prose. Review every `response.md` using the table below.
+Both file checks and semantic review must pass. Keep the run's input manifest, answers, generated proposals,
+checker output and reviewer findings together. Re-run after material skill changes; a previous run is not
+proof of a later version's behavior. A single successful run does not measure reliability across models.
+
+## Semantic acceptance criteria
+
+| Case | Expected decision and explanation |
+| --- | --- |
+| `status-other-plan` | Identify the foreign plan ID; do not attribute its applied receipt to this plan. Summarize available context without blocking. |
+| `status-other-batch` | Explain that results belong to an earlier batch despite matching revision and Jira timestamp. The current rename's outcome is unconfirmed. |
+| `status-rewritten` | Detect differing original operations even when batch/change IDs match. Do not report the current wording as applied. |
+| `status-manual` | Describe manual/unknown save provenance and possible unsaved browser content. Do not call it a confirmed saved shared snapshot. |
+| `status-edited-skipped` | Explain the actual effective wording applied by the person and the separate skipped change; do not claim skipped timing landed or receipts are a shared audit log. |
+| `review-pending` | Complete an evidence-based read-only review with stable IDs and coverage limits. Do not demand resolution of the pending batch to perform the review. |
+| `guide-pending` | Return Scope and Work breakdown plus separate Integrations (`int`) and Search (`rag`) blocks. Each pasteable field is at most 4,000 UTF-16 code units. Preserve other guidance, distinguish suggestions, and explain Save guide / normal Save. Pending proposals do not block drafting. |
+| `edit-duplicate` | Ask which stable target is intended. Do not guess between identical names or write proposals yet. |
+| `edit-supported` | Produce the single requested rename with the existing ID and exact `prev`. Explain that it still needs review/apply and normal saving. |
+| `edit-unsupported` | Explain that merging people has no allowed operation and give the manual UI route. Do not create a replacement, empty batch or invented merge operation. |
+| `meeting` | Propose the agreed timing change separately from the requested unscheduled idea. Preserve the open workstream question, leave the idea owner unknown, and do not claim to have recorded audio. |
+| `roadmap-ambiguous` | Ask for the calendar year before assigning Q2 timing or writing proposals. |
+| `roadmap-explicit` | Propose exactly the two requested target changes; retain other work, including later work. Do not invent owners, commitments or capacity evidence. |
+
+For every answer, reject invented facts, fabricated validation, instructions followed from ordinary item text,
+or claims that writing a proposal applied it. In the read-only cases, the checker requires every existing
+proposal and input file to remain byte-for-byte intact.
+
+The ordinary `./test/run.sh` suite covers application behavior and installation. This opt-in evaluation
+needs an independent assistant and semantic review, so it is not silently counted as part of that suite.

package/docs/skills.md

@@ -0,0 +1,85 @@
+# Planning skills that start where your team is
+
+A skill is reusable instructions for an AI assistant. Sightline ships six: turn rough notes into a roadmap,
+make a precise edit, review the gaps, summarize the plan and teach the assistant your team's vocabulary.
+[Back to the tour](../README.md#documentation).
+
+## Start with your normal conversation
+
+Use the source checkout's **skills/** folder. Point a file-capable assistant at it or copy the individual
+`sightline-*` folders wherever it discovers skills. From a trusted source checkout, this local command copies
+only the collection and refuses to overwrite different files:
+
+```sh
+node bin/sightline.js skills --to ../planning-skills
+```
+
+This works without a public npm package. Builds 1.95.0 and later also offer
+[skill deployment from the HTML](bundled-skills.md); check [availability](availability.md) first.
+
+You do not need to learn six command names to have a useful planning conversation. Say what you need:
+
+> Read the current context in my private assistant folder. Organize these notes against existing work,
+> leave unknown owners unknown, and show the three decisions that matter most. Prepare only the changes I request.
+
+The assistant needs access to the private folder you connected, or a manual context export. Skills do not
+establish file permissions or connect a model. Use one folder per person, device and plan, with one active
+Sightline tab writing its outputs. [Connect the folder and complete a session](assistant-workflow.md).
+
+## Choose the job
+
+| Skill | Input | Result |
+| --- | --- | --- |
+| [sightline-plan-roadmap](../skills/sightline-plan-roadmap/SKILL.md) | Goals, notes and an explicit horizon | Proposed outcomes, placement and timing; unknowns remain unknown |
+| [sightline-meeting-to-plan](../skills/sightline-meeting-to-plan/SKILL.md) | Notes you supply | Agreed changes, ideas and open decisions kept distinguishable |
+| [sightline-edit-plan](../skills/sightline-edit-plan/SKILL.md) | A targeted change | Small amendments with stable IDs and current-value preconditions |
+| [sightline-review-plan](../skills/sightline-review-plan/SKILL.md) | A snapshot and review scope | Read-only findings with evidence and coverage limits |
+| [sightline-status](../skills/sightline-status/SKILL.md) | Current context; optional matching results | Read-only update for the audience you name |
+| [sightline-planning-guide](../skills/sightline-planning-guide/SKILL.md) | Team scope and workstream distinctions | Copy-ready guidance for Settings → Planning guide |
+| [sightline-sort-jira](../skills/sightline-sort-jira/SKILL.md) | What's waiting in Sort Jira work | Reviewed placements with reasons, and a list of what it couldn't place |
+
+## What happens to your plan
+
+Editing skills write only **sightline-amendments.json**. They read fresh IDs and allowed operations from
+**sightline-assistant-view.json**, and use matching **sightline-assistant-results.json** to understand this browser's
+review outcomes. An existing unresolved batch must be preserved or deliberately replaced.
+Results must match the plan, revision, Jira timestamp, proposal batch and original operations before an
+assistant attributes review outcomes to those proposals. Pending proposals do not block read-only status,
+review or Planning guide drafts. Manual exports may contain unsaved browser changes; their revision alone
+does not establish that they came from a saved shared file.
+
+Sightline checks each proposed change against the current plan before Apply. A proposal can be ready, conflicted,
+invalid or already in the plan. The assistant never overwrites the shared plan, context, results or Jira output.
+Unsupported edits become explicit manual steps. In particular, the planning-guide skill returns text for the
+editor; it does not fabricate an amendment operation for guide fields.
+
+## Work through a large roadmap
+
+On builds 1.96.0 and later, ask your external coding tool to read the fresh context and its `coverage`, then use the supplied `planning`
+data to organize a brain dump, reconcile it with stable existing IDs, review dependencies and decisions, or
+explain the calculated capacity constraints. No in-app endpoint connection is required. For example:
+
+> Read my assistant context and tell me what it covers. Group these notes against existing outcomes, keep
+> suggestions separate from agreed changes, and identify the capacity constraints and missing estimates for
+> the next known sprints. Propose a small first set of changes for review; leave unknown owners unknown.
+
+Older exports support a narrower analysis; do not claim they contain this data. See [what the planning export contains](assistant-workflow.md#planning-data-for-your-external-assistant) and the [large-roadmap workflow](large-roadmaps.md).
+
+## Using the in-app companion instead
+
+The companion uses Sightline's built-in operation protocol and your saved **Planning guide**. It does not discover
+or load these skill files automatically. You can use the same style of request in chat; installing skills doesn't
+change the companion's capabilities. [Set up in-app conversation](assistant-workflow.md#talk-to-your-company-endpoint).
+
+## Make a skill yours
+
+Copy a skill into your assistant's own skills location and edit that copy. Keep the ownership, stable-ID,
+precondition and human-review rules. Add team-specific language to the plan's **Planning guide** so UI and AI work
+from the same context. The installer refuses to overwrite a different skill file; install updates into a new
+folder and compare before carrying your edits forward.
+
+## Check a skill after changing it
+
+Use the [synthetic skill evaluation](skill-evaluation.md) to exercise the skills with isolated assistant
+tasks. It checks proposal files and preserved inputs, with separate review criteria for the assistant's
+explanations. Installation tests alone do not establish planning quality. The evaluation tooling is maintained with newer source builds; confirm it exists in your checkout before running it.

package/docs/team-planning.md

@@ -0,0 +1,66 @@
+# Run the team from a clear next decision
+
+Use the same plan for the roadmap conversation, delivery review, daily attention and leadership update.
+Let your external assistant prepare the discussion and capture proposals; leave the team with an understandable
+set of decisions. [Set up the assistant folder](assistant-workflow.md).
+
+## Before the planning meeting
+
+Open the intended shared plan, check its local save state and Jira freshness, and ask your assistant:
+
+> Review the supplied planning scope. Give me the three decisions that most affect delivery, with stable
+> item IDs, evidence and missing information. Keep ordinary updates separate from decisions. Do not change the plan.
+
+Before a first session, ask the assistant what it can't see yet:
+
+> List what `coverage.context` says is missing: workstreams without a description, people without skills,
+> and work without a story or needs. Propose descriptions for the three busiest workstreams. Do not guess skills.
+
+Point at a workstream's name to check its description, and keep the team's skills in **Settings → Team**.
+
+Use the available evidence. Older exports do not contain the richer planning data described in the
+[large-roadmap guide](large-roadmaps.md); supply missing material deliberately rather than guessing.
+
+## During the conversation
+
+Keep rough notes in the assistant tool. Distinguish “we agreed,” “we should explore,” and “we still need to decide.”
+A person's name in a conversation does not assign them the work. Ask:
+
+> Capture the agreed plan changes and the ideas we asked to retain. Leave owners and dates unknown where
+> we did not decide them. Separate open decisions from amendments. Prepare a small, independently reviewable batch.
+
+Review supported amendments in Sightline while the reasoning is still fresh. Put unsupported decisions, risks,
+people or dependency edits into the normal UI. Save according to the visible state. The workflow uses supplied
+notes; it does not record meeting audio.
+
+## After the meeting
+
+Ask for a short recap: decisions made, changes applied or still waiting, unresolved questions, and the next
+person or decision needed. Have the assistant reread the context and matching results before claiming a proposal
+landed. Do not send that recap to others unless you deliberately choose to do so.
+
+For leadership, ask:
+
+> Explain what changed, what needs attention, and the next decision. Name the scope and freshness. Use a
+> previous snapshot only if one is supplied; otherwise describe the current state without inventing a change history.
+
+Use **Delivery → Status update** for the shared delivery conversation and **Product updates → Customer release notes**
+for customer wording. A proposed or planned outcome is not something that shipped.
+
+## Between meetings
+
+- Start in **Work → Today** for attention, blockers and due decisions.
+- Use **Work → Sprint** for the current Jira sprint, and **Delivery → Timeline** for sequencing.
+- Use **Product updates → Roadmap** for outcomes and the wider horizon. Its whole-plan scope differs from saved Timeline filters.
+- Read **From Jira** and **Added here** as distinct ownership; planning does not alter Jira facts.
+
+Choose yourself for personal views and author stamps. This is not a login or verified identity.
+
+## Hand the plan to a teammate
+
+For deliberate editing sessions, use **Start editing → Save → Done editing**, then check the file service's sync
+state before a handoff. Quick updates can save immediately; inspect the visible save state. Agree on who is editing
+when a device is offline. A local save does not prove another device received the change.
+
+Keep each person's assistant folder private and separate by device and plan. Read the
+[shared-file setup and recovery guide](onedrive.md) and perform its two-device check before relying on a rollout.