changeledger 0.4.0 → 0.6.0

package/src/viewer/public/index.html

@@ -61,6 +61,8 @@
       </div>
     </div>
 
+    <div id="toast-container" class="toast-container" aria-live="assertive" aria-atomic="true"></div>
+
     <script type="module" src="/app.js"></script>
   </body>
 </html>

package/src/viewer/public/styles.css

@@ -1262,3 +1262,286 @@ body {
     padding: 8px 8px;
   }
 }
+
+/* config editor tabs and form (113924) */
+.config-section {
+  border-bottom: 1px solid var(--line);
+}
+.config-tabs {
+  display: flex;
+  gap: 2px;
+  padding: 12px 20px 0;
+  border-bottom: 1px solid var(--line);
+}
+.config-tab {
+  padding: 6px 14px;
+  border: 1px solid transparent;
+  border-bottom: none;
+  border-radius: 6px 6px 0 0;
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 500;
+  position: relative;
+  bottom: -1px;
+}
+.config-tab.active {
+  background: var(--bg);
+  border-color: var(--line);
+  color: var(--text);
+}
+.config-form-structured {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+.config-group {
+  margin: 0;
+  padding: 14px 20px;
+  border: none;
+  border-bottom: 1px solid var(--line);
+}
+.config-group legend {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--muted);
+  padding: 0;
+  margin-bottom: 8px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+.config-group label {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--muted);
+  margin-bottom: 8px;
+}
+.config-group input[type="text"],
+.config-group input:not([type]) {
+  padding: 6px 10px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--bg);
+  color: var(--text);
+  font-size: 13px;
+}
+.config-group textarea {
+  padding: 6px 10px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--bg);
+  color: var(--text);
+  font-size: 12px;
+  font-family: ui-monospace, monospace;
+  resize: vertical;
+}
+.config-group label.config-checkbox {
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  color: var(--text);
+}
+.config-checkbox input[type="checkbox"] {
+  width: 16px;
+  height: 16px;
+  accent-color: var(--accent);
+}
+.config-type-row {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 6px 0;
+  margin: 0;
+  border: 0;
+  border-bottom: 1px solid var(--line);
+  flex-wrap: wrap;
+}
+.config-type-row:last-child {
+  border-bottom: none;
+}
+.config-group .config-type-row legend {
+  min-width: 80px;
+  font-size: 13px;
+  color: var(--text);
+  text-transform: none;
+  letter-spacing: normal;
+  margin: 0;
+}
+.config-type-row label:first-of-type {
+  flex: 1 1 240px;
+}
+.config-type-row select {
+  padding: 4px 8px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--bg);
+  color: var(--text);
+  font-size: 12px;
+}
+.config-note {
+  font-size: 11px;
+  color: var(--muted);
+  margin: 0 0 6px;
+}
+.config-readonly-note {
+  font-style: italic;
+}
+.config-group-internal p {
+  display: flex;
+  gap: 12px;
+  margin: 4px 0;
+  font-size: 12px;
+}
+.config-readonly-label {
+  color: var(--muted);
+  font-family: ui-monospace, monospace;
+  min-width: 120px;
+}
+.config-readonly-value {
+  color: var(--text);
+}
+.config-migration-card {
+  padding: 16px 20px;
+}
+.config-migration-card h3 {
+  margin: 0 0 8px;
+  font-size: 14px;
+  color: #f7ab57;
+}
+.config-migration-preview {
+  margin-top: 12px;
+}
+.config-migration-yaml {
+  max-height: 300px;
+  overflow: auto;
+  padding: 10px;
+  background: #0b0d11;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  font-size: 11px;
+  font-family: ui-monospace, monospace;
+  color: #d9e1ea;
+  margin: 8px 0;
+}
+.config-migration-ok {
+  color: #56d364;
+  font-size: 12px;
+}
+.config-future-schema p {
+  padding: 0 20px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.config-schema-badge {
+  display: inline-block;
+  margin: 12px 20px 4px;
+  padding: 2px 8px;
+  border-radius: 4px;
+  background: rgba(248, 81, 73, 0.15);
+  color: #ff8078;
+  font-size: 11px;
+  font-weight: 600;
+}
+.config-section-note {
+  padding: 0 20px;
+  font-size: 11px;
+  color: var(--muted);
+  font-style: italic;
+}
+
+/* Native confirm dialog (cl-confirm-dialog) */
+.cl-confirm-dialog {
+  margin: auto;
+  padding: 28px 28px 24px;
+  min-width: 320px;
+  max-width: 440px;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 14px;
+  box-shadow: 0 24px 72px rgba(0, 0, 0, 0.55);
+  color: var(--text);
+}
+.cl-confirm-dialog::backdrop {
+  background: rgba(4, 6, 10, 0.75);
+  backdrop-filter: blur(4px);
+}
+.cl-confirm-message {
+  margin: 0 0 20px;
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--text);
+}
+.cl-confirm-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
+/* Toast notifications */
+.toast-container {
+  position: fixed;
+  bottom: 24px;
+  right: 24px;
+  z-index: 100;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  pointer-events: none;
+}
+.toast {
+  padding: 12px 16px;
+  border-radius: 10px;
+  font-size: 13px;
+  font-weight: 500;
+  max-width: 340px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.45);
+  animation: toast-in 0.2s ease;
+  pointer-events: auto;
+}
+.toast-error {
+  background: #2a1215;
+  border: 1px solid rgba(248, 81, 73, 0.45);
+  color: #ff8078;
+}
+.toast-info {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  color: var(--text);
+}
+@keyframes toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Prompt input inside confirm dialog */
+.cl-prompt-label {
+  display: block;
+  margin-bottom: 6px;
+  color: var(--muted);
+  font-size: 12px;
+}
+.cl-prompt-input {
+  display: block;
+  width: 100%;
+  margin: 0 0 16px;
+  padding: 8px 12px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--bg);
+  color: var(--text);
+  font-size: 13px;
+  box-sizing: border-box;
+}
+.cl-prompt-input:focus {
+  outline: none;
+  border-color: var(--accent);
+}

package/src/viewer/server/router.mjs

@@ -5,8 +5,12 @@ import { gitRefs } from '../../git.mjs';
 import { publicDir } from '../../paths.mjs';
 import { loadRepoAsync } from '../../repo.mjs';
 import {
+  applyConfigMigration,
   changeStatus,
+  patchProjectConfig,
+  previewConfigMigration,
   readProjectConfig,
+  readProjectConfigStructured,
   repairProjectPath,
   resolveProjects,
   saveProjectConfig,
@@ -87,12 +91,15 @@ export function createRequestListener(cwd, localOnly, token) {
       const route = url.pathname;
       const params = url.searchParams;
 
-      if (
-        req.method === 'POST' &&
-        ['/api/status', '/api/project-config', '/api/project-path', '/api/project-remove'].includes(
-          route,
-        )
-      ) {
+      const WRITE_ROUTES = new Set([
+        '/api/status',
+        '/api/project-config',
+        '/api/project-config-patch',
+        '/api/project-config-migrate-apply',
+        '/api/project-path',
+        '/api/project-remove',
+      ]);
+      if (req.method === 'POST' && WRITE_ROUTES.has(route)) {
         if (!isAuthorizedWrite(req, token)) {
           send(res, 403, MIME['.json'], JSON.stringify({ error: 'unauthorized write' }));
           req.destroy();
@@ -121,14 +128,17 @@ export function createRequestListener(cwd, localOnly, token) {
             }
             const { projects } = resolveProjects(cwd, localOnly);
             const options = { localOnly };
-            const result =
-              route === '/api/status'
-                ? changeStatus(projects, payload)
-                : route === '/api/project-config'
-                  ? saveProjectConfig(projects, payload, options)
-                  : route === '/api/project-path'
-                    ? repairProjectPath(projects, payload, options)
-                    : unregisterProject(projects, payload, options);
+            let result;
+            if (route === '/api/status') result = changeStatus(projects, payload);
+            else if (route === '/api/project-config')
+              result = saveProjectConfig(projects, payload, options);
+            else if (route === '/api/project-config-patch')
+              result = patchProjectConfig(projects, payload);
+            else if (route === '/api/project-config-migrate-apply')
+              result = applyConfigMigration(projects, payload);
+            else if (route === '/api/project-path')
+              result = repairProjectPath(projects, payload, options);
+            else result = unregisterProject(projects, payload, options);
             const { code, body } = result;
             send(res, code, MIME['.json'], JSON.stringify(body));
           } catch (error) {
@@ -154,6 +164,22 @@ export function createRequestListener(cwd, localOnly, token) {
         send(res, code, MIME['.json'], JSON.stringify(body));
         return;
       }
+      if (route === '/api/project-config-structured') {
+        const { projects } = resolveProjects(cwd, localOnly);
+        const { code, body } = readProjectConfigStructured(projects, params.get('project'));
+        send(res, code, MIME['.json'], JSON.stringify(body));
+        return;
+      }
+      if (route === '/api/project-config-migrate-preview') {
+        const { projects } = resolveProjects(cwd, localOnly);
+        const { code, body } = previewConfigMigration(
+          projects,
+          params.get('project'),
+          params.get('revision'),
+        );
+        send(res, code, MIME['.json'], JSON.stringify(body));
+        return;
+      }
       if (route === '/api/git') {
         const rawId = params.get('id');
         if (rawId && !/^[0-9]{8}-[0-9]{6}$/.test(rawId)) {

package/templates/config.yml

@@ -1,13 +1,17 @@
 # ChangeLedger — repo configuration
 # Repo specifics: documentation language, change types and active stages per type.
 
+# Schema version — used to detect and migrate outdated configurations.
+# Run `changeledger config migrate --dry-run` to inspect available migrations.
+schema_version: 1
+
 # Language for generated documentation CONTENT. Structure (headings, keys, enums)
-# is always English. See AGENTS.md §8.
+# is always English. See `changeledger context spec`.
 language: en
 
 # Definition of Ready policy. When true (default), changes are documented
 # test-grade and implemented via TDD; `changeledger check` warns on criteria ↔ task
-# coverage gaps. Set false for exploratory repos. See AGENTS.md §11.
+# coverage gaps. Set false for exploratory repos. See `changeledger context spec`.
 tdd: true
 
 # Default SemVer impact for a completed change. A change may override its type
@@ -38,7 +42,8 @@ stages: [request, investigation, proposal, specification, plan, log]
 
 # Active stages per type. The viewer shows only these.
 # `review_required: true` makes the change pass through `in-review` (an
-# independent subagent review) before universal human validation. See AGENTS.md §5/§6.
+# independent subagent review) before universal human validation. See
+# `changeledger context implement` and `changeledger context review`.
 types:
   feature:
     stages: [request, investigation, proposal, specification, plan, log]

package/templates/contract/blocked.md

@@ -0,0 +1,6 @@
+# Blocked — Resolve Before Implementing
+
+Do not resume implementation merely because context was requested. Inspect the
+blocked task and Log. If the impediment is resolved within authorized scope,
+record the decision, restore the task and move `blocked → in-progress`. If it
+requires scope or product judgment, ask the human. Never bypass the block.

package/templates/contract/close.md

@@ -0,0 +1,18 @@
+# Closing Accepted Work
+
+The human accepted this change. Graduate persistent truth before archiving:
+
+- `changeledger graduate <id> <spec-slug>` creates a new spec.
+- `changeledger graduate <id> <spec-slug> --into` links an existing spec and
+  refreshes `updated` without overwriting the spec body (the agent edits the body manually).
+- `changeledger graduate <id> --skip [reason]` records that no persistent truth
+  changed.
+- `changeledger graduate --pending` lists unresolved graduation decisions.
+- `changeledger archive <id>` hides the completed record from the default board.
+
+Specs have no lifecycle: minimal frontmatter (`title`, `updated`, `tags`) plus
+free Markdown describing current capabilities, architecture or domain truth.
+The change is the journey; the spec is the destination.
+
+After closure, share a brief retrospective. New work needs a new authorized
+change; `done` never reopens.

package/templates/contract/core.md

@@ -0,0 +1,71 @@
+# ChangeLedger — Core Contract
+
+Documents under `.changeledger/` are the source of truth. Code is their
+reflection. Work is planned and documented before code is written.
+
+## Non-negotiable fast path
+
+1. Work starts with conversation. Read-only investigation may clarify a request,
+   but create no change or implementation artifact until there is enough clarity
+   to document faithfully **and** the human explicitly authorizes documentation. A direct request such
+   as “create the change” is authorization; never invent missing requirements.
+2. The human authorizes scope, approves drafts and accepts the final result. The
+   agent decides how to divide and execute work within that authorized scope.
+3. Capture every authorized change in `.changeledger/changes/`. The document
+   wins when code and documentation disagree.
+4. Never implement a `draft`. After approval, work one change at a time on a
+   non-main branch and commit the approved change document before code.
+5. Keep lifecycle, tasks, ownership and Log current while working.
+6. For types that require review, use a fresh clean-context reviewer before
+   human validation.
+7. Stop at `in-validation`. The agent never accepts on the human's behalf.
+8. After human acceptance, graduate persistent truth or record an explicit skip,
+   then archive the done change.
+
+Humans consume changes in `changeledger view`; write for the rendered view.
+
+## Lifecycle
+
+```text
+draft → approved → in-progress
+in-progress → in-review → in-validation → done   [review required]
+in-progress → in-validation → done               [no review required]
+in-review → in-progress                           [review retry]
+in-review → blocked → in-progress                 [review escalation]
+in-validation → in-progress                       [human rejection]
+(draft | approved | in-progress | blocked) → discarded
+```
+
+- `draft`: documentation awaiting human approval; no implementation.
+- `approved`: ready to start after the Git/worktree checks.
+- `in-progress`: implementation underway.
+- `in-review`: independent review required.
+- `in-validation`: stop and wait for human acceptance or rejection.
+- `blocked`: an impediment or decision needs resolution.
+- `done`: terminal; the human accepted the complete result.
+- `discarded`: terminal tombstone; never reopen it.
+
+`changeledger status <id> <status>` enforces agent-owned transitions and does not accept `done` or `discarded`.
+Humans approve and validate in the viewer; use
+`changeledger discard <id> "<reason>"` for a discarded change. `done` and `discarded`
+never reopen.
+
+## Context modes
+
+Valid modes: implement, review, spec, release.
+
+- `changeledger context spec`: author or refine a change.
+- `changeledger context implement`: execute an approved change.
+- `changeledger context review`: independently verify completed work.
+- `changeledger context release`: plan portable delivery metadata.
+- `changeledger context <change-id>`: infer the correct context from lifecycle.
+
+## Operational discovery
+
+Prefer structured CLI queries before scanning files:
+
+- `changeledger list --status approved`: find approved changes ready to implement.
+- `changeledger graduate --pending`: find accepted changes whose graduation decision is unresolved.
+
+Run `changeledger help` or `changeledger <command> --help` for exact CLI syntax.
+Structure is always English; narrative content follows `.changeledger/config.yml`.

package/templates/contract/discarded.md

@@ -0,0 +1,5 @@
+# Discarded — Terminal
+
+This change records work explicitly decided against. Preserve its reason and
+dependencies; do not implement, graduate or reopen it. Any later reconsideration
+requires a new authorized change.

package/templates/contract/implement.md

@@ -0,0 +1,52 @@
+# Implementing an Approved Change
+
+1. Keep one concern per change. Work necessary for the authorized objective may
+   update Specification, Plan and Log. If related work materially expands observable scope, obtain explicit human
+   authorization before adding it; propose independent work separately.
+2. Never implement approved changes on `main`, `master`, or `dev`. Inspect the
+   worktree first. If unrelated changes exist, do not include them silently.
+3. Commit the approved change documentation before touching implementation code.
+   Implement one change at a time.
+4. Commit a completed unit before continuing when another task or shared edit makes attribution
+   ambiguous. Commit messages reference the id. If shared files make a combined commit
+   unavoidable, record it explicitly and name every change sharing the surface.
+5. Keep the change current with `changeledger task`, `changeledger log`,
+   `changeledger owner` and `changeledger status`.
+6. Follow the Specification exactly. Write a failing test from each criterion,
+   make it pass, then refactor. Do not silently drift the document.
+7. Leave no TODO/FIXME, dead code or unrelated residue without explicit agreement.
+8. When implementation and tasks are complete, move to `in-review` if the type
+   requires independent review; otherwise move to `in-validation` and stop.
+
+## Correction isolation
+
+After review `fail --retry`, keep the candidate correction uncommitted while a
+fresh clean-context reviewer checks it. If it fails again, iterate on that diff.
+After `pass`, commit the confirmed correction and ledger truth before asking for
+human validation.
+
+After human rejection (`in-validation → in-progress`), keep the correction
+uncommitted until the human confirms it. Do not start another task or change
+while a correction waits; the worktree is the isolation boundary.
+
+## Triage friction at handoff; retrospect after completion
+
+Before handing the human completed or blocked work, classify discovered
+friction:
+
+- If necessary to fulfill the purpose of an active change, update that change.
+- If it is an operational step such as verify, commit, graduate or archive,
+  execute or record it in the current flow.
+- If independent or materially larger, propose its type, title, and reason to
+  the human. Create the draft only after explicit authorization.
+- If too vague for backlog, mention it without creating a file.
+
+When a change reaches `done`, also share a brief retrospective with the human.
+
+## Useful commands
+
+- `changeledger status <id> <status>`
+- `changeledger task <id> done|block <n> [reason]`
+- `changeledger log <id> "<message>"`
+- `changeledger owner <id> <name|->`
+- `changeledger check [id]`

package/templates/contract/readiness.md

@@ -0,0 +1,19 @@
+# Definition of Ready
+
+With `tdd: true`, an approved change is ready only when:
+
+1. Every behavioral requirement is a concrete `CRn` with actual inputs, exact
+   outputs/effects and literal errors. Edge cases get separate criteria.
+2. Every implementation task names target file(s)/area(s), verification, and the
+   criteria it satisfies. It is sized to one red-green cycle.
+3. TDD is explicit: write the failing test from the criterion, make it pass, then
+   refactor. The implementer chooses how, not what, to test.
+
+Repos may configure `readiness.target_patterns` and
+`readiness.verification_patterns`. For manual checks, prefer a structural rule
+such as `verification_patterns: ["verify:"]`, then write evidence like
+`verify: manual Android device check` instead of listing every possible manual phrase.
+
+`changeledger check` reports missing Given/When/Then, uncovered or unknown CRs,
+tasks without traceability, and CR-bearing tasks without a configured target and
+verification (`draft` warnings; approved/in-progress errors).

package/templates/contract/release.md

@@ -0,0 +1,25 @@
+# Portable Release Planning
+
+- `changeledger release init <version>` adopts release tracking at an existing
+  stable SemVer; the baseline contains changes already done.
+- `changeledger release plan [--json]` deterministically selects unreleased done
+  changes and calculates the next version without writing.
+- `changeledger release record <version>` records exactly that plan in
+  `.changeledger/releases/<version>.yml`.
+
+Defaults live under `release.impacts` in `.changeledger/config.yml`; a change may
+override its type with `release_impact` (`none|patch|minor|major`).
+
+ChangeLedger owns portable membership and SemVer. The operating agent owns
+stack-specific version files, project gates, commits, tags and publishing.
+Never infer that every ChangeLedger repository uses npm or GitHub.
+
+## Routine release preparation
+
+Routine release preparation is operational work.
+Version bumps, release manifests, quality gates, packaging, commits, tags and publishing do not require a ChangeLedger change by themselves.
+Do not create a change only to group those routine steps.
+
+If preparation reveals a functional fix, release-workflow change or persistent documentation, capture it as a separate change.
+Complete that change and rerun `changeledger release plan` before `changeledger release record <version>`.
+Keep this workflow stack-agnostic; do not assume npm, GitHub or specific manifest filenames.

package/templates/contract/review.md

@@ -0,0 +1,19 @@
+# Independent Review
+
+Review-required work must be checked by a fresh subagent with clean context and
+a model sized to the difficulty. Independence is correctness, not an
+optimization. The reviewer verifies every criterion, every Plan task, tests,
+the actual diff and absence of residue; it does not trust the implementer's
+summary.
+
+Delegate for a clear reason and boundary. Do not over-shard by file or tiny edit,
+and do not overlap write surfaces without an explicit integration plan.
+
+- Pass: `changeledger review <id> pass` → `in-validation`.
+- Fixable defect: `changeledger review <id> fail --retry "<reason>"` →
+  `in-progress`.
+- Scope/decision escalation: `changeledger review <id> fail --block "<reason>"`
+  → `blocked` for the human.
+
+After a retry, the correction stays uncommitted until another clean reviewer
+passes it. Then commit correction + ledger before asking for human validation.