axstack 0.53.0 → 0.54.0

package/docs/workflows.md

@@ -256,7 +256,10 @@ for explicit ownership transfer.
   fenced. Fable also serves the bounded triggers in
   [Standing contracts](../skills/axstack/references/contracts.md).
 - `axstack-spec` writes observable acceptance, exclusions, decisions, and one
-  user-approved revision baseline. Linear through the executor MCP is the
+  user-approved revision baseline. Its [shared format](../skills/axstack-spec/references/format.md)
+  opens with the human decision brief, groups binding requirements by capability,
+  and separates evidence/history. Review checks readability alongside completeness.
+  Linear through the executor MCP is the
   default only for `defi-com` repositories; GitHub Issues and repository
   Markdown are explicit alternatives and the stores for other repositories.
   A GitHub baseline pins the issue URL and approved body digest. Preflight

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks T3 Code capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/diligence.md

@@ -29,7 +29,10 @@ paths, and stale references. Bind the result to the exact head and base.
 
 For research, reopen cited sources for answer-changing claims before the
 driver folds verified claims. For a draft spec, compare it with Align decisions
-before user approval: flag anything dropped, added, or softened. For tickets,
+before user approval: flag anything dropped, added, or softened. For a draft spec,
+check readability alongside completeness using the
+[shared format](../../axstack-spec/references/format.md#readability-review).
+For tickets,
 map every spec acceptance item to a capability's acceptance. Before candidate
 publication, compare the author receipt with its evidence folder: red/green
 logs exist, and counts, SHAs, and paths match. For release preparation, compare

package/skills/axstack/scripts/check-staged-file-tokens.js

@@ -22,38 +22,28 @@ try {
   } catch (error) {
     if (error.code !== 'ENOENT') throw error;
   }
+  if (git('ls-files', '--unmerged', '-z')) throw Error('Unmerged index entries must be resolved before measurement');
   const paths = git('diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z').split('\0').filter(Boolean);
-  const offenders = [];
+  const advisories = [];
   for (const path of paths) {
     if (ignoredPath.test(path) || asset.test(path) || ignores.some((glob) => glob.match(path))) continue;
     if (git('ls-files', '--stage', '-z', '--', path).startsWith('160000 ')) continue;
-    const bytes = Number(git('cat-file', '-s', `:${path}`));
+    const size = git('cat-file', '-s', `:${path}`).trim();
+    const bytes = Number(size);
+    if (!/^\d+$/.test(size) || !Number.isSafeInteger(bytes)) {
+      throw Error(`Invalid blob size for ${JSON.stringify(path)}: ${JSON.stringify(size)}`);
+    }
     if (bytes <= 20000) continue;
     if (git('diff', '--cached', '--numstat', '--no-renames', '-z', '--', path).startsWith('-\t')) continue;
     // Consume the blob fully: closing a pipeline at line five can cause SIGPIPE.
     const firstLines = git('cat-file', 'blob', `:${path}`).split('\n', 5).join('\n');
     if (/@generated|auto[- ]?generated|do not edit|code generated by/i.test(firstLines)) continue;
-    offenders.push(`${JSON.stringify(path)}: ${Math.floor(bytes / 4)} tokens`);
+    advisories.push(`${JSON.stringify(path)}: ${bytes} bytes`);
   }
-  if (offenders.length) {
-    console.error(`Staged files exceed 5000 tokens (20000 bytes; tokens = floor(bytes / 4)):
-${offenders.join('\n')}
-
-Split each file before committing:
-1. Find seams: group top-level units by responsibility.
-2. Create a folder named after the original file, with one module per responsibility.
-   TS: foo.ts -> foo/types.ts, foo/parse.ts, foo/index.ts.
-   Rust: foo.rs -> foo/mod.rs + submodules with re-exports.
-   Svelte: child components + a .ts module for pure logic.
-   Specs: one spec per describe block or behaviour.
-   HTML docs: one doc per topic, linked from an index.
-3. Keep the public surface stable via re-exports, or update all imports in the same commit.
-4. Move code verbatim first, then refactor in a separate commit.
-5. Aim for ~3000 tokens per file.
-6. Stage the new files and re-commit.
-If truly generated or recorded data, add a glob to ${JSON.stringify(ignoreFile)}
-or give the file a generated banner in its first 5 lines.`);
-    process.exit(1);
+  if (advisories.length) {
+    console.error(`Advisory: staged files above 20000 bytes (size alone does not block committing):
+${advisories.join('\n')}
+Review file structure and responsibilities; no size-only split or approval is required.`);
   }
 } catch (error) {
   console.error(`Staged-file token check failed: ${error.message}`);

package/skills/axstack-implement/SKILL.md

@@ -166,11 +166,17 @@ applied or found not applicable in the `Simplification:` line of the
 including evidence and retained complexity.
 
 Before every commit, the author runs the
-[staged-file token gate](../axstack/scripts/check-staged-file-tokens.js)
+[staged-file size check](../axstack/scripts/check-staged-file-tokens.js)
 with `bun` from the target repository.
-If the gate fails, split files per its instructions before retrying.
-Never bypass the staged-file token gate.
-Record the staged-file token gate result in the implementation receipt.
+Successful staged-file size measurements, including files above 20,000 bytes,
+are advisory and exit 0.
+Never require splitting files solely for size.
+Never request user approval solely for file size.
+Review file structure and responsibilities even when size is advisory.
+Git, read, malformed-size and unmerged-index errors must fail with a nonzero exit.
+Resolve measurement errors before committing; keep repository-owned checks enforceable.
+Preserve the check's exclusions, but never hide authored files behind generated banners or ignore globs.
+Record the staged-file size check result in the implementation receipt.
 
 ## 5. Verify and return the candidate
 
@@ -199,7 +205,7 @@ Owner: <profile + session ID + worktree>
 Scope: <approved spec + capability | small-change intent | maintenance snapshot>
 Shape: <total> lines vs base <sha>; bulk: <buckets>; theme: <one line>
 TDD: <normal red/green | structure-preserving old-green/same-check-new-green evidence | F-repair base-green/removal-inversion-red/rewording-green evidence>
-Token limit: <staged-file gate command + observed result before each commit>
+Token limit: <staged-file size check command + observed advisories/errors before each commit>
 Simplification: <applied | not-applicable> — evidence: <diff locations and checks>; retained complexity: <necessary complexity and why>
 Acceptance: <checks + observed results>
 Dependencies: <parent revisions or none>

package/skills/axstack-spec/SKILL.md

@@ -43,8 +43,9 @@ and the lifecycle's [audit skill](../axstack-audit/SKILL.md) hook.
    access before any issue write. Record the repository and identity checked.
    Missing access preserves the GitHub selection and stops the phase without
    mutation or fallback. Markdown mode skips external access preflight.
-3. **Draft with decision evidence.** Write observable acceptance criteria
-   and explicit exclusions in the selected store. Only when the scope identity
+3. **Draft with decision evidence.** Follow the
+   [readable specification format](references/format.md) when drafting in the
+   selected store. Only when the scope identity
    carries a sketch, include the [design lens](../axstack/references/design-lens.md)
    sketch in the approved revision's `Design` section and its `Usage` line in
    acceptance. First record the driver's
@@ -90,7 +91,8 @@ and the lifecycle's [audit skill](../axstack-audit/SKILL.md) hook.
    [Diligence](../axstack/references/diligence.md) to check the draft against
    the Align decisions for anything dropped, added, or softened.
 5. **Snapshot the baseline.** Record the approved revision identity and a
-   concise repository Markdown counterpart. In Linear mode, the native
+   concise repository Markdown counterpart pointing to the same requirements,
+   not a second human or agent contract. In Linear mode, the native
    document remains authoritative. In GitHub mode, the approved issue body is
    authoritative and its GitHub issue URL plus SHA-256 body digest identifies
    the exact approved revision. In Markdown mode, the agreed repository path does.

package/skills/axstack-spec/references/format.md

@@ -0,0 +1,88 @@
+# Readable specification format
+
+Use this structure inside the selected authoritative store. It changes layout,
+not store selection, adviser review, diligence, approval or snapshot authority.
+
+## Decision brief
+
+Begin with a decision brief before execution detail and history.
+Keep identity and status compact, with review-round history after current requirements.
+For example: title, revision, draft or approved status, authoritative location.
+
+- In the opening, explain the problem, why it matters and the proposed change.
+- When useful, include a concrete before/after example or flow in the opening.
+- State included and excluded scope in the brief.
+- Surface consequential risks, trade-offs and unverified boundaries in the brief.
+- Collect all decisions needed from the user in the opening, with options and
+  consequences; say explicitly when none remain.
+
+Give enough context for an informed decision. Link each consequential choice
+or risk to its precise execution requirement. Never bury a material decision
+or risk only in supporting detail.
+
+## Execution requirements
+
+Group precise requirements and observable acceptance by capability, using stable
+IDs where useful. Include behavior, interfaces, data, invariants, failure cases
+and validation that determine success. Put routine file-by-file task and PR
+sequencing in Tickets, retaining meaningful design and rollout constraints in the spec.
+State each rule once and reference it from other sections.
+Technical execution detail remains binding wherever stored, including linked detail.
+Human and agent views share one authoritative specification.
+Resolve brief/detail conflicts before approval rather than declaring one view expendable.
+
+Use headings, short requirement blocks or lists for scanning. Use a table when
+it helps compare choices, rather than putting whole paragraphs in cells.
+Do not impose word caps, mandatory tables, an extra artifact or ceremony.
+The example below is adaptable guidance, not another required document.
+The existing readback identifies and explains this same revision; it is not
+a duplicate whole spec with separate requirements.
+
+## Evidence and history
+
+Keep history, evidence and adviser receipts separate from current requirements.
+Place provenance, commands, review-round dispositions and change logs here or
+link their existing records. They explain the requirements, not override them.
+When amending a draft, update current criteria in place and keep the change log
+as history. Preserve approved snapshots immutable and mark supersession through
+metadata or links outside the approved bytes. Use the existing material-revision
+and snapshot procedure for a changed baseline; a new draft is not approval.
+
+## Readability review
+
+For readability review, verify a human can identify what changes, why, decisions
+and risks from the opening and an implementer can find exact requirements without
+reconstructing history. Assess this alongside completeness before the existing
+specification checkpoint. Return unclear or conflicting passages for revision
+under the existing review and approval rules.
+
+## Compact example
+
+```markdown
+# Export the filtered view — r2, draft
+Authoritative location: <selected store URL or repository path>
+
+## Decision brief
+Problem/why: exports ignore the table filter, forcing users to clean the file.
+Change: export what the user is viewing.
+Before: export downloads the whole dataset. After: it downloads filtered rows.
+Included: CSV export from this table. Excluded: scheduled exports and new formats.
+Trade-off/risk: an active filter can omit rows users expect; label the action
+“Export filtered rows” (EXP-1). Unverified: large exports on low-memory devices.
+Decision needed: approve filtered export with the explicit label, or retain
+whole-dataset export and its cleanup cost. Proposed choice: filtered export.
+
+## Execution requirements
+### Filtered export
+EXP-1: On click, capture the active filter and visible column order, label the
+action “Export filtered rows”, and export only matching rows in those columns.
+Acceptance for EXP-1: with a two-row dataset and a filter matching one row,
+the CSV contains that row and the visible columns in order; with a filter
+matching zero rows, the CSV contains the header only.
+
+## Evidence and history
+Source: <observed current behavior and revision>.
+Adviser receipts: <links bound to r2>; approval: pending.
+Change log: r2 incorporates the zero-row case into EXP-1 acceptance.
+Previous approved baseline, if any: <immutable ref>; supersession: pending approval.
+```