@erclx/aitk 0.104.1 → 0.106.0

package/standards/publish.md

@@ -12,7 +12,7 @@ Governs the scan an author runs against finished text on its way out, the form a
 Does not govern:
 
 - Which characters are banned, and the formatting the text carries: `markdown.md`
-- The voice and word choice the text is written in: `prose.md`
+- The voice and rhythm the text is written in: the `write-human` skill
 - The phase-label rule and the table of surfaces each namespace may appear on: `versioning.md`
 - Which gap a given surface has, and what it publishes through, which that surface names for itself
 
@@ -24,7 +24,7 @@ Run the scan as an explicit step against the finished text. Having read the unde
 
 ## Banned characters
 
-`markdown.md` holds the character bans and `prose.md` holds the banned words. Read both at scan time rather than working them from memory, then scan the drafted text and rewrite each occurrence.
+`markdown.md` holds the character bans and the banned words alike. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
 
 Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
 

package/standards/readme.md

@@ -5,7 +5,7 @@ description: Readme voice, structure, and content conventions
 
 # Readme reference
 
-Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so `prose.md` yields to it there. The yield covers voice alone. The spelling rules and banned words in `prose.md` stay in force, as do the punctuation and formatting rules in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the spelling rules, banned words, punctuation, and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
@@ -15,13 +15,13 @@ Governs every `README.md`: voice, heading structure, required and optional secti
 
 Does not govern:
 
-- Spelling and banned words in README prose: `prose.md`, which yields the voice and keeps the rest
-- Punctuation and formatting in README prose: `markdown.md`, which yields nothing
+- Rhythm and sentence construction in README prose: the `write-human` skill, which yields the voice and keeps the rest
+- Spelling, banned words, punctuation, and formatting in README prose: `markdown.md`, which yields nothing
 - Product scope and goals: `requirements.md`
 
 ## Voice
 
-Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice in `prose.md`, since its reader has already committed and arrived looking for a fact.
+Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice the `write-human` skill carries, since its reader has already committed and arrived looking for a fact.
 
 - Address the reader in second person. First-person plural needs an authoring organization as its antecedent, so a single-maintainer project has none to use.
 - Use contractions wherever the sentence reads better for one. Do not force them in.

package/standards/skill.md

@@ -17,8 +17,8 @@ Does not govern:
 
 - Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
 - Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
-- Voice and word choice in a skill body: `prose.md`
-- Punctuation and formatting in a skill body: `markdown.md`
+- Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
+- Punctuation, formatting, and word choice in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
 - The domain conventions a skill cites, each of which belongs to the standard that owns it
 

package/standards/standard.md

@@ -17,8 +17,8 @@ Governs each authored standard under `standards/`: its stated jurisdiction, succ
 
 Does not govern:
 
-- The voice and word choice a standard is written in: `prose.md`
-- The punctuation and formatting a standard is written in: `markdown.md`
+- The voice, rhythm, and sentence construction a standard is written in: the `write-human` skill
+- The punctuation, formatting, and word choice a standard is written in: `markdown.md`
 - The shape of any artifact a standard governs, which is that standard's own subject
 
 ## What a working standard looks like

package/standards/teach.md

@@ -20,8 +20,8 @@ Does not govern:
 - Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
 - One question measured in depth before anyone can plan against it: `groundwork.md`
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
-- Voice and word choice: `prose.md`
-- Headings, punctuation, and file references: `markdown.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
 - When a workspace opens at all, and the procedure that runs one, which belong to the surface driving it
 
 ## What a working workspace looks like

package/standards/versioning.md

@@ -16,8 +16,8 @@ Does not govern:
 - The format of a phase label, which is project-specific by the rule below
 - Task filenames and board layout: `tasks.md`
 - Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
-- Voice and word choice in any text carrying a label: `prose.md`
-- Punctuation and formatting in any text carrying a label: `markdown.md`
+- Voice, rhythm, and sentence construction in any text carrying a label: the `write-human` skill
+- Punctuation, formatting, and word choice in any text carrying a label: `markdown.md`
 
 ## Phase labels
 

package/standards/wireframes.md

@@ -17,8 +17,8 @@ Does not govern:
 
 - Tokens, typography, spacing, and the rest of the visual system: `design.md`
 - The mechanism behind a surface: `context.md`
-- Voice and word choice in wireframe prose: `prose.md`
-- Punctuation and formatting in wireframe prose: `markdown.md`
+- Voice, rhythm, and sentence construction in wireframe prose: the `write-human` skill
+- Punctuation, formatting, and word choice in wireframe prose: `markdown.md`
 
 ## What a working wireframe looks like
 
@@ -75,7 +75,7 @@ Reference the context entry from the wireframe by path when a reader needs the m
 ## Maintenance
 
 - When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
-- The Behavior and Copy prose around an ASCII block is prose and follows `prose.md` and `markdown.md`. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
+- The Behavior and Copy prose around an ASCII block is prose and follows `markdown.md` and the `write-human` skill. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
 
 ## Template
 

package/tooling/astro/manifest.toml

@@ -15,17 +15,17 @@ packages = [
 ]
 
 [scripts]
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro dev"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
 "build" = "astro check && astro build"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro preview"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 "astro" = "astro"
 "typecheck" = "astro check"
 "setup" = "./scripts/setup.sh"
 
 [scripts.override]
-"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) bash scripts/screenshot.sh"
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro dev"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) astro preview"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 
 [gitignore]
 "# Astro" = [".astro/"]

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -25,7 +25,7 @@ esac
 [ -f "$file" ] || exit 0
 
 # The audit verb owns the ban sets, so this hook carries no copy of them. The
-# awk this replaces parsed the word bans out of the project's own prose.md,
+# awk this replaces parsed the word bans out of the project's own standards,
 # hardcoded the em-dash and semicolon, and reached none of the spellings, so a
 # British spelling passed at edit time and a corpus check caught it later with
 # nothing in between explaining the difference. A ban class added to the verb
@@ -79,7 +79,7 @@ elif [ -n "$empty" ]; then
 fi
 
 if [ -n "$hits" ]; then
-  found=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite the sentence (do not lazy-swap). A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
+  found=$(printf 'Standards-audit: markdown.md violations in %s. Rewrite the sentence (do not lazy-swap). A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
   msg="${msg:+$msg$nl}$found"
 fi
 

package/tooling/vite-react/manifest.toml

@@ -11,13 +11,13 @@ packages = [
 ]
 
 [scripts]
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite"
 "build" = "tsc --noEmit && vite build"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite preview"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite preview"
 "typecheck" = "tsc --noEmit"
 "setup" = "./scripts/setup.sh"
 
 [scripts.override]
 "build" = "tsc --noEmit && vite build"
-"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite"
-"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) vite preview"
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite"
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite preview"

package/tooling/web/configs/scripts/worktree-port.sh

@@ -3,10 +3,18 @@ set -euo pipefail
 
 # Prints a port for this working directory: the base itself in a normal
 # checkout, and the base plus a per-worktree offset in a linked git worktree,
-# so two worktrees of one repository never serve on one port.
+# so two worktrees of one repository never serve on one port. A folder left
+# behind after its worktree was removed is refused rather than served, since
+# every port it derives lands on the one the main checkout wanted.
 
 base="${1:-0}"
 band=50
+worktrees_dir=".claude/worktrees"
+
+refuse() {
+  echo "worktree-port: $1 is a leftover worktree folder, because $2." >&2
+  echo "worktree-port: a port derived here collides with the main checkout, so remove the folder, or set WORKTREE_PORT_OFFSET to serve from it anyway." >&2
+}
 
 offset() {
   if [[ -n "${WORKTREE_PORT_OFFSET:-}" ]]; then
@@ -14,23 +22,53 @@ offset() {
     return
   fi
 
-  local git_dir common_dir name
-  git_dir=$(git rev-parse --git-dir 2>/dev/null) || {
+  local here git_dir common_dir toplevel dir name
+  here=$(pwd -P)
+
+  if ! git_dir=$(git rev-parse --git-dir 2>/dev/null); then
+    # Git refuses outright when a `.git` file names an administrative directory
+    # that is gone, which is what removing a worktree by hand leaves behind.
+    # Outside a repository there is no pointer at all and the base is correct.
+    dir=$here
+    while [[ "$dir" != / ]]; do
+      if [[ -f "$dir/.git" ]]; then
+        refuse "$dir" "its .git file names an administrative directory that is gone"
+        return 1
+      fi
+      [[ -d "$dir/.git" ]] && break
+      dir=$(dirname "$dir")
+    done
     echo 0
     return
-  }
+  fi
+
   common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || {
     echo 0
     return
   }
+  toplevel=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo 0
+    return
+  }
+  toplevel=$(cd "$toplevel" && pwd -P)
 
   if [[ "$(cd "$git_dir" && pwd -P)" == "$(cd "$common_dir" && pwd -P)" ]]; then
+    # The main checkout answers here, and so does every directory under it,
+    # including a folder whose `.git` was deleted along with its worktree,
+    # since git then walks upward and reports the parent repository. Location
+    # is the only signal separating the two, so a directory sitting under the
+    # worktrees folder is refused rather than handed the base port.
+    if [[ "$here/" == "$toplevel/$worktrees_dir/"?* ]]; then
+      refuse "$here" "no worktree is registered for it"
+      return 1
+    fi
     echo 0
     return
   fi
 
-  name=$(basename "$(git rev-parse --show-toplevel)")
+  name=$(basename "$toplevel")
   echo $(($(printf '%s' "$name" | cksum | cut -d' ' -f1) % band + 1))
 }
 
-echo $((base + $(offset)))
+value=$(offset) || exit 1
+echo $((base + value))

package/tooling/web/manifest.toml

@@ -42,13 +42,13 @@ packages = [
 "test:run" = "vitest run --reporter=verbose"
 "test:ui" = "vitest --ui"
 "test:coverage" = "vitest run --coverage"
-"test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) playwright test"
-"test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) playwright test --ui"
+"test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test"
+"test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --ui"
 "test:e2e:report" = "playwright show-report"
 "check:full" = "./scripts/verify.sh && bun run test:e2e"
 
 [scripts.override]
-"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) bash scripts/screenshot.sh"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
 
 [gitignore]
 "# Build" = ["dist/"]

package/tooling/web/reference.md

@@ -16,7 +16,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
-- `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone.
+- `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone. It refuses a folder left under the worktrees directory after its worktree was removed, rather than printing a port for it.
 
 ## What stays in per-stack adapters
 
@@ -40,6 +40,9 @@ Two worktrees of one repository run the same stack, so a fixed port makes the se
 - Derive every served port from `scripts/worktree-port.sh`. Never write a port literal into a script string.
 - Read `WORKTREE_PORT_OFFSET` in a config and add it to the stack's default port. Unset yields the default, so a plain clone keeps the port it has always served on.
 - Draw the offset from a band of 50, hashed from the worktree folder name. Two worktrees can hash to one offset, so set `WORKTREE_PORT_OFFSET` by hand to break a tie.
+- Expect a non-zero exit and no port from a folder left under `.claude/worktrees/` once its worktree is gone. Git reports the parent repository from inside one, so the helper cannot read it as a worktree and every base it serves would land on the main checkout's port. Both shapes refuse, and they reach differently. A folder whose own `.git` was deleted refuses only under that directory, since location is the only thing separating it from an ordinary subdirectory the base port is correct for. A folder whose `.git` names a pruned administrative directory refuses wherever it sits, because a pointer to nothing is broken regardless of where the folder is.
+- Call it as `VAR=$(bash scripts/worktree-port.sh) && export VAR && <server>`, never as the shorter `VAR=$(bash scripts/worktree-port.sh) <server>`. An assignment prefix discards the exit status of its own substitution, so the shorter form starts the server with `VAR` set to the empty string, every config reads that back as an offset of zero, and the refusal lands on the port it was raised to protect. The assignment alone carries the status, which is what the `&&` reads.
+- Set `WORKTREE_PORT_OFFSET` by hand to serve from such a folder anyway. That is the one override, and it is checked before any directory test.
 - Force-replace `dev` and `preview` through `[scripts.override]`. Both stacks' scaffolds define those keys, and a plain `[scripts]` entry never replaces a key the scaffold already wrote.
 - Set `strictPort` on every dev and preview server. A server that walks to the next free port serves where nothing is looking for it.
 - Set Playwright `reuseExistingServer: false`. Reuse attaches to whatever answers on the port, which reports a pass against another branch's code and prints nothing to say so.

package/standards/prose.md

@@ -1,89 +0,0 @@
----
-title: Prose reference
-description: Voice, language, what prose may claim, and frontmatter wording for reference markdown
----
-
-# Prose reference
-
-Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it.
-
-The yield covers voice alone. The language rules below stay in force on every surface, including the surfaces no automated check reaches, as do the mechanics in `markdown.md`.
-
-## Scope
-
-Governs voice, word choice, what prose may claim about its subject and its sources, and frontmatter wording wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, yields on voice alone where that standard states one, and carries no template because voice is written across every document and has none of its own to shape.
-
-Does not govern:
-
-- Headings, list and paragraph structure, code spans, the form a date takes, punctuation, emphasis, and file references: `markdown.md`
-- What sections a document has, or what belongs in each: the standard for that document type
-- Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
-- Phase-label and semver discipline: `versioning.md`
-- The scan that applies these bans to finished text on its way out: `publish.md`
-- Code style and language conventions, which are governance rules rather than a standard
-
-## Voice
-
-- Write for a developer who is scanning, not studying. Every sentence should be understandable on first read.
-- Use active voice. Default to present tense unless past or future tense is factually correct.
-- Prioritize direct verbs and plain words, using the minimum necessary. Write `use` not `utilize`, `help` not `facilitate`, `is` not `serves as`.
-- Vary sentence length and opening structure to break uniform cadence. Do not start consecutive sentences the same way.
-- Use substantive connectives where flow matters, but never add words solely for rhythm. Terse reference prose needs no padding.
-- Be direct on established facts. Hedge on genuinely uncertain claims.
-- Assume developer-level technical knowledge. Skip hand-holding explanations.
-- Front-load key information in each paragraph. Keep paragraphs concise and scannable.
-- Every sentence must provide new information. Cut redundant context.
-
-## Language
-
-- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
-- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
-- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
-- Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
-- Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
-- Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
-- Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
-- Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
-- Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
-- Do not name a person, company, or product to borrow its authority. Name a source only where the claim turns on who made it.
-- Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
-- Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
-
-The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and the bans here reach the words a sentence chooses and the claims it makes. A surface applying both reads both files.
-
-## Frontmatter descriptions
-
-When frontmatter carries a short `title` or `description` used for catalog display:
-
-- `title`: sentence case, identifies the file uniquely against its siblings in the same catalog. Proper nouns retain their casing. No trailing period.
-- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. Lead with concrete subjects, strip filler like "guide to", "overview of", or "documentation about". No trailing period, no leading article (`the`, `a`).
-- Do not mechanically reuse the H1 as the description.
-
-## Examples
-
-Each pair shows a banned pattern and its fix.
-
-```markdown
-Bad: The configuration file serves as the central hub for all build settings.
-Good: Configuration lives in `vite.config.ts`.
-```
-
-```markdown
-Bad: In order to configure the server, you'll need to ensure that the port is set.
-Good: Set `port` in the server config.
-```
-
-```markdown
-Bad: It's not just a cache. It's a system for intelligent memory management.
-Good: The cache is an LRU store. It evicts the least-recently-used entry when full.
-```
-
-```markdown
-Bad: Leveraging the retry mechanism, developers can build more resilient integrations.
-Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
-```
-
-```markdown
-Bad: It might be worth considering whether to enable caching.
-Good: Enable caching for read-heavy endpoints. Skip it for writes.
-```