aiwg 2026.9.7 → 2026.9.9

package/agentic/code/addons/aiwg-hooks/hooks/aiwg-session.cjs

@@ -210,8 +210,28 @@ async function main() {
       break;
     }
 
+    case undefined:
+    case '':
+      // Invoked with no subcommand. This is the SessionStart hook path: anything
+      // printed here lands at the top of every session transcript, so stay silent
+      // and exit clean. Help is available explicitly via `help`/`--help`. (#2543)
+      break;
+
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(usage());
+      break;
+
     default:
-      console.log(`
+      console.error(`Unknown command: ${command}`);
+      console.error(usage());
+      process.exitCode = 1;
+  }
+}
+
+function usage() {
+  return `
 AIWG Session Manager
 
 Usage:
@@ -226,8 +246,7 @@ Examples:
 
   aiwg-session.cjs record aiwg-security-review-2025-01-15 --workflow security-review
   aiwg-session.cjs list
-`);
-  }
+`;
 }
 
 main().catch(err => {

package/agentic/code/addons/aiwg-utils/rules/auto-compact-continue.md

@@ -1,5 +1,9 @@
 ---
 enforcement: high
+triggers:
+  - "should I keep working"
+  - "context is getting long"
+  - "should I stop here"
 ---
 
 # Auto-Compact and Continue

package/agentic/code/addons/aiwg-utils/rules/delivery-policy.md

@@ -4,6 +4,12 @@ id: delivery-policy
 severity: HIGH
 applies_to: [all-agents]
 tags: [git, workflow, project-config, branching]
+triggers:
+  - "should I open a pull request"
+  - "do I branch for this"
+  - "can I commit to main"
+  - "how does this project deliver changes"
+  - "force push policy"
 ---
 
 # Delivery Policy Rule

package/agentic/code/addons/aiwg-utils/rules/escalation-discipline.md

@@ -1,5 +1,9 @@
 ---
 enforcement: high
+triggers:
+  - "should I use a stronger model"
+  - "is this worth escalating"
+  - "model tier"
 ---
 
 # Escalation Discipline

package/agentic/code/addons/aiwg-utils/rules/human-authorization.md

@@ -5,6 +5,13 @@ severity: HIGH
 safety-critical: true
 applies_to: [all-agents]
 tags: [authorization, scope, safety]
+triggers:
+  - "am I allowed to do this"
+  - "do I need permission for this"
+  - "can I delete this"
+  - "should I close this issue"
+  - "acting on a finding"
+  - "is this in scope"
 ---
 
 # Human Authorization Rules

package/agentic/code/addons/aiwg-utils/rules/instruction-comprehension.md

@@ -1,5 +1,10 @@
 ---
 enforcement: high
+triggers:
+  - "what did the user actually ask for"
+  - "did I follow the instructions"
+  - "the user repeated themselves"
+  - "user says that is not what I asked"
 ---
 
 # Instruction Comprehension Rules

package/agentic/code/addons/aiwg-utils/rules/research-before-decision.md

@@ -1,5 +1,10 @@
 ---
 enforcement: high
+triggers:
+  - "which library should I use"
+  - "why does this keep failing"
+  - "I am guessing at this api"
+  - "before I decide"
 ---
 
 # Research Before Decision Rules

package/agentic/code/addons/aiwg-utils/rules/respect-repo-access-manifest.md

@@ -1,5 +1,12 @@
 ---
 enforcement: high
+triggers:
+  - "register a repo in the workspace manifest"
+  - "add a repo to the access manifest"
+  - "register a repo"
+  - "repo access manifest"
+  - "am I allowed to write to this repo"
+  - "is this repo authorized"
 ---
 
 # Respect Repo Access Manifest
@@ -10,16 +17,33 @@ workspace manifest is `.aiwg/aiwg.config` `workspace` + `repos`. Legacy
 `.aiwg/ops/security/repo-access.manifest.yaml` and
 `.aiwg/security/repo-access.manifest.yaml` remain compatibility fallbacks.
 
+To **register a repo in the workspace manifest**, add a repo to the access manifest,
+or list repositories that are unlisted and therefore denied, use
+`aiwg repo-access add | remove | audit`. Registration is an operator decision:
+propose the command, do not run it on your own authority.
+
 ## Rule
 
 Before reading deeply, editing, committing, pushing, commenting on issues, or taking service actions against a repo path, run or mentally apply:
 
 ```bash
 aiwg repo-access check --path <repo-or-file> --action <read|write|commit|push|issue-comment|service-action|destructive>
+# register a repo in the workspace manifest / add a repo to the access manifest:
+aiwg repo-access add --path <p> --name <n> --allow read,write
 ```
 
 If the repo/path is unlisted, deny by default. Ask the operator to add or update
-the manifest before proceeding. For every listed member, load that member's own
+the manifest before proceeding — the registration command is:
+
+```bash
+aiwg repo-access add --path <repo-or-file> --name <name> \
+  --allow read,write,commit,push[,issue-comment,service-action] [--notes "..."]
+aiwg repo-access remove --name <name>
+aiwg repo-access audit   # git repos under the workspace root with no manifest entry
+```
+
+Registration is the operator's decision: propose the exact command, do not run it
+on your own authority. For every listed member, load that member's own
 `.aiwg/aiwg.config`; never reuse the workspace root's delivery, remotes, tracker
 actor, or signing policy.
 
@@ -76,7 +100,8 @@ If asked to edit an adjacent repo that is not listed:
 
 1. Stop before editing.
 2. Explain that the manifest denies unlisted repo work.
-3. Ask for a manifest update or explicit operator instruction to add the repo.
+3. Ask for a manifest update or explicit operator instruction to add the repo,
+   quoting the `aiwg repo-access add` command that would register it.
 
 If asked to comment on an issue in a handoff-only repo:
 

package/agentic/code/addons/aiwg-utils/rules/skill-discovery.md

@@ -1,5 +1,10 @@
 ---
 enforcement: high
+triggers:
+  - "does AIWG have a skill for this"
+  - "how do I find a capability"
+  - "is there a command for this"
+  - "AIWG does not seem to have"
 ---
 
 # Skill Discovery Rules

package/agentic/code/addons/aiwg-utils/rules/subagent-scoping.md

@@ -1,5 +1,10 @@
 ---
 enforcement: high
+triggers:
+  - "how many subagents should I spawn"
+  - "should I delegate this"
+  - "how do I split this work"
+  - "parallel agents"
 ---
 
 # Subagent Scoping Rules

package/agentic/code/addons/aiwg-utils/rules/tool-quota.md

@@ -1,5 +1,9 @@
 ---
 enforcement: high
+triggers:
+  - "how many times should I retry"
+  - "this command keeps failing"
+  - "am I in a loop"
 ---
 
 # Tool Quota and Loop Detection

package/agentic/code/addons/aiwg-utils/skills/steward/SKILL.md

@@ -124,15 +124,24 @@ Use this recovery ladder:
    aiwg regenerate
    ```
 
-5. If discovery itself is stale after source edits or a failed deploy, rebuild
-   the index and verify the route:
+5. If discovery itself is stale after source edits, a failed deploy, or an
+   install-root change (`npm link`), rebuild the index and verify the route.
+   **The framework graph indexes the AIWG corpus and can only be built at the
+   install root** — running the build step in a consumer project fails with
+   "No scan directories found". Only the sync step runs in the project:
 
    ```bash
+   cd "$(aiwg installation show --json | jq -r .actualRoot)"   # or the known install root
    aiwg index build --graph framework --force
+
+   cd <your project>
    aiwg index sync --backend fortemi-core --graph framework
    aiwg discover "<original user need>"
    ```
 
+   `aiwg discover --backend local` works as an immediate workaround while the
+   framework graph is unavailable.
+
 6. Reload the provider session when `aiwg use`, `aiwg refresh`, or
    `aiwg regenerate` changes provider-facing files.
 

package/agentic/code/extensions/corpus-templates/templates/TEMPLATE-citations.md

@@ -12,31 +12,73 @@ funders:                             # extracted from paper acknowledgements (om
   - id: PROF-F-funder-slug
     grant-id: "AGENCY-GRANT-NUMBER"  # if stated; null if not
 status: induction-complete           # optional: placeholder | pending-acquisition | acquisition-deficit
+acquisition-obstacle:                # required when status is pending-acquisition/acquisition-deficit
+  state: not-attempted               # not-attempted | credential-required | structurally-unobtainable | artifact-absent
+  detail: ""                         # the specific obstacle, e.g. "needs HF_TOKEN"; never a bare boolean
+  paths-tried: []                    # ["resolve/main/README.md 200", "raw/main/README.md 401"]
+bibliography:                        # how the edges below were established
+  source: bbl                        # bbl | inline-thebibliography | pdf-reference-list
+  count: 0                           # entries in the compiled bibliography
+  count-method: 'counted \bibitem in .bbl'   # single-quoted: YAML "\b" is a backspace escape
+  unique-count:                      # when printed ≠ unique (duplicate entries), else omit
 ---
 
 # REF-XXX Citation Network
 
 ## Outgoing: Papers This Work Cites
 
-| # | Title | Authors | Year | DOI/URL | Inducted REF |
-|---|-------|---------|------|---------|--------------|
-| 1 | {cited title} | {Lastname et al.} | YYYY | arXiv:NNNN.NNNNN | REF-YYY |
-| 2 | {cited title} | {authors} | YYYY | DOI / URL | — |
-| ... | ... | ... | ... | ... | ... |
+| # | Title | Authors | Year | DOI/URL | Inducted REF | Confirmed by |
+|---|-------|---------|------|---------|--------------|--------------|
+| 1 | {cited title} | {Lastname et al.} | YYYY | arXiv:NNNN.NNNNN | REF-YYY | arxiv-id |
+| 2 | {cited title} | {authors} | YYYY | DOI / URL | — | printed-entry |
+| ... | ... | ... | ... | ... | ... | ... |
 
 <!--
 Outgoing rules:
+- Membership comes from the COMPILED bibliography, in this order of preference:
+    1. `.bbl` (`\bibitem` for natbib/plain, `\entry{}` for biblatex)
+    2. `\begin{thebibliography}` inline in the `.tex`
+    3. the reference list in the extracted PDF text
+    4. the shipped `.bib` — ONLY to enrich metadata for entries already confirmed by 1-3
+  The shipped `.bib` is the author's library, not the reference list. An entry present in
+  `.bib` and absent from the compiled bibliography is NOT a citation; asserting it
+  fabricates an edge. A 15-entry gap between the two is ordinary.
 - One row per distinct cited work in the paper's reference list (cap at ~30 most relevant
   if the paper has 100+ refs; note which references were cut and why in Notes).
 - "Inducted REF" column links to corpus REFs when the cited work is in the corpus.
   Mark as "—" (em dash) when the cited work is not (yet) in the corpus.
+- "Confirmed by" records HOW the edge was established: `arxiv-id`, `exact-title`, or
+  `printed-entry` (read the entry directly). Title similarity against a corpus index is
+  not confirmation — author-year collisions defeat it (e.g. "Zou et al. 2023" may be GCG
+  or Representation Engineering: same first author, same year, different work). Normalise
+  brace-escaped titles (`{AI}`, `{Prompt}-{Driven}`) before comparing.
 - Authors column: "Lastname et al." for ≥4 authors; full list for ≤3.
 - DOI/URL: prefer arXiv ID format `arXiv:NNNN.NNNNN` for arXiv preprints; DOI for
   peer-reviewed; URL for blog posts / technical reports.
+- Direction is a check, not an assumption: a work cannot cite something published after
+  it. Verify both publication dates before writing the edge.
 - When an outgoing row points to an inducted REF, that target REF's Incoming table
   MUST contain a corresponding row pointing back here. See bidirectionality below.
 -->
 
+## Rejected Candidates
+
+| # | Title | Authors | Year | Why rejected |
+|---|-------|---------|------|--------------|
+| 1 | {candidate title} | {authors} | YYYY | `.bib`-only — absent from compiled `.bbl` |
+
+<!--
+Rejected-candidate rules:
+- Record every candidate edge dropped after investigation, so a later extraction pass
+  does not silently reintroduce it.
+- Most common reason: present in the shipped `.bib`, absent from the compiled
+  bibliography. Others: wrong node after author-year disambiguation; direction
+  impossible by publication date.
+- REF ids here are deliberately NOT edges. Corpus tooling stops treating a section as
+  an edge source at this heading, so a rejection cannot assert the edge it records.
+- Omit this section only when no candidate was rejected.
+-->
+
 ## Incoming: Papers That Cite This Work
 
 | # | Title | Authors | Year | DOI/URL | Inducted REF |
@@ -66,12 +108,18 @@ Incoming rules:
 - **Author overlap**: shared authors with REF-AAA, REF-BBB (same lab / research line).
 - **Methodological lineage**: this paper extends / contradicts / parallels REF-XXX's approach.
 - **External replication state**: known independent replications or rebuttals not yet inducted.
-- **Reference list size**: total cited works in PDF vs included here (e.g., "PDF has 87 refs;
-  this sidecar includes the 30 most relevant per Outgoing rules").
+- **Reference list size**: entries in the COMPILED bibliography vs included here, stating
+  the counting method (e.g., "66 `\bibitem` in .bbl; this sidecar includes the 30 most
+  relevant per Outgoing rules"). Never `.bib` size, and never a sum of artifacts — summing
+  `.bib` and `.bbl` without dedup has produced counts inflated 2-3x. Note printed-vs-unique
+  where they differ.
 
-If acquisition is incomplete, document it here:
-- "PDF not acquired (paywall); Outgoing references deferred."
-- "Reference list extraction pending."
+If acquisition is incomplete, document the named obstacle and the paths tried, not just
+the fact:
+- "PDF not acquired — structurally-unobtainable: closed access; Unpaywall zero OA locations,
+  Semantic Scholar reports abstract elided, no arXiv preprint. Outgoing deferred."
+- "PDF not acquired — credential-required: dataset repo returns 401 to anonymous client on
+  `raw/main`; `resolve/main` also 401. Needs HF_TOKEN."
 }
 
 <!--

package/agentic/code/extensions/corpus-templates/templates/TEMPLATES-README.md

@@ -107,6 +107,8 @@ When backfilling, do **not** restructure heading content silently. Preserve the
 | `pdf_hash` | yes when PDF exists | string | SHA-256 of `pdfs/full/REF-XXX-*.pdf` |
 | `affiliation-primary` | optional | string or PROF-O ID | Primary author's institution |
 | `status` | optional | enum | `placeholder`, `pending-acquisition`, `acquisition-deficit` for partial inductions |
+| `acquisition-obstacle` | required when status is `pending-acquisition`/`acquisition-deficit` | object | `state` (`not-attempted`, `credential-required`, `structurally-unobtainable`, `artifact-absent`), `detail` (the specific obstacle), `paths-tried` (each path and what it returned). A bare boolean cannot be triaged |
+| `bibliography` | recommended on citation sidecars | object | `source` (`bbl`, `inline-thebibliography`, `pdf-reference-list`), `count`, `count-method`, optional `unique-count`. Counts come from the compiled bibliography, never `.bib` size or a sum of artifacts |
 
 The `pdf_hash` field is the load-bearing integrity check — verify with `sha256sum pdfs/full/REF-XXX-*.pdf` when refreshing.
 

package/agentic/code/frameworks/ops-complete/rules/ops-safety.md

@@ -1,5 +1,11 @@
 ---
 enforcement: critical
+triggers:
+  - "is this command destructive"
+  - "can I run this safely"
+  - "blast radius"
+  - "this needs sudo"
+  - "interactive command"
 ---
 
 # Ops Safety Rules

package/agentic/code/frameworks/research-complete/docs/bibliographic-services.md

@@ -0,0 +1,76 @@
+# Bibliographic services: what each is good for, and where each will mislead you
+
+Operating characteristics of the services the census, retraction, and acquisition
+steps depend on. Measured across a 12-paper batch, 2026-09-12. Re-measure and
+update the date when these change — the failure modes below are behavioural, not
+documented guarantees.
+
+The point of this table is not the happy path. It is that **one of these services
+returns plausible, well-formed, badly wrong data with no error**, and an agent
+discovering the ecosystem from scratch has no way to know which.
+
+## Service table
+
+| Service | Use for | Do **not** use for | Auth | Observed failure |
+|---|---|---|---|---|
+| Semantic Scholar | citation counts, influential counts, venue corroboration | — | key strongly recommended | HTTP 429 even at 25 s spacing |
+| OpenAlex | `is_retracted` | **citation counts** — splits preprint/published records; 18× undercount observed | none | none; returns wrong data silently |
+| OpenReview | venue/acceptance confirmation | — | none | — |
+| ACL Anthology / PMLR | published version, page ranges | — | none | PMLR asset lives at `raw.githubusercontent.com/mlresearch/...`; the intuitive proceedings path 404s |
+| Crossref / Unpaywall / Europe PMC | OA routing, bibliographic metadata | — | none (Unpaywall wants `mailto`) | — |
+| PubPeer | post-publication concerns | — | — | HTTP 403 to non-browser clients |
+| DBLP | venue fallback | — | — | anti-bot challenge; returns HTML, not JSON |
+
+## The OpenAlex count trap
+
+OpenAlex indexes the arXiv preprint record separately from the published record and
+does not merge them. For REF-2532 (ROME) it returns `cited_by_count: 178` where
+Semantic Scholar returns **3,205** — an 18× undercount. Title-search does not fix
+it; the best-cited match was still the arXiv record.
+
+This is a trap rather than a limitation because of *when* an agent reaches for it.
+OpenAlex is the obvious fallback when Semantic Scholar throttles: unauthenticated,
+generous limits, returns a plausible-looking integer. Substituting it silently
+records counts an order of magnitude wrong, with no error and no signal. The
+corpus then carries a number that looks like evidence and is not.
+
+**Calibration rule.** Never substitute a citation-count source without checking it
+against a known-high-count paper first. A source that returns 178 for a
+3,000-citation paper is not a fallback, it is data corruption. One calibration
+query catches it.
+
+**Provenance rule.** Record the source and the date with every count. A count
+without a provenance line cannot be compared against a later refresh and cannot be
+audited when two sources disagree. Record a null result as a null result —
+`is_retracted: false, OpenAlex, 2026-09-12` — never as the absence of a check.
+
+## Throttling budget
+
+Semantic Scholar is the best source for counts and the most aggressive throttler.
+Measured: 4 of 12 succeeded on a first pass at ~4 s spacing; a retry pass at **25 s
+spacing still lost 4 of 8**. The 429 body points at the API-key form.
+
+Budget roughly five minutes of wall-clock for a 12-paper census, and **record
+misses as misses** rather than substituting a source that has not been calibrated.
+
+## Permanent access limitations
+
+PubPeer returns 403 to this client, so the corpus has never carried a PubPeer
+signal; radars record "PubPeer not checked" as a permanent access limitation, which
+is honest. DBLP returns an Anubis challenge page rather than JSON, which fails like
+a parse error rather than a block — worth naming, since DBLP is the natural venue
+fallback when Semantic Scholar throttles.
+
+## API keys
+
+A Semantic Scholar key removes the throttling problem and is strongly recommended
+for any batch. Key handling follows
+[`token-security`](../../sdlc-complete/rules/token-security.md) without
+exception: a mode-600 file, loaded at the point of use, never passed as a command
+argument, never echoed, never committed.
+
+```bash
+# Correct: loaded inline at point of use, scoped to the call
+curl -s -H "x-api-key: $(cat ~/.config/semanticscholar/token)" \
+  "https://api.semanticscholar.org/graph/v1/paper/..."
+```

package/agentic/code/frameworks/research-complete/lint/uncertainty-registered.yaml

@@ -0,0 +1,31 @@
+id: research/uncertainty-registered
+name: Stated uncertainty must name an obstacle
+description: >
+  An uncertainty written only into prose is invisible to the verification contract.
+  The contract governs declared checks and returns pass/incomplete/blocked for things
+  someone thought to declare, so "no OpenReview query was run" never surfaces as
+  incomplete and the "never report skipped verification as success" rule is never
+  violated — the skipped verification was never registered as verification at all.
+
+  Flags a clause that states an unperformed action against a verification target the
+  agent could have acted on (OpenReview, ACL Anthology, camera-ready, PDF, retraction
+  or citation census, code URL, venue) with no obstacle named nearby. Accepts the
+  statement once it names a specific obstacle — HTTP status, credential requirement,
+  rate limit, paywall, anti-bot wall, unknown endpoint — or records an outcome with a
+  date, which is what turns "I did not check" into "I could not check, because".
+
+  Matching is scoped to a clause, not a line: corpus prose keeps whole paragraphs and
+  changelog table rows on one line, and line-scoped matching related unrelated clauses.
+  A verification target is required precisely so the paper's own unverified claims are
+  left alone — this rule must not discourage honest limitation sections.
+
+  Severity is warn because this is a prose heuristic. Measured on a 2,544-reference
+  corpus: 34 flagged clauses, of which roughly 31 are genuine unperformed checks —
+  including every gap a hand post-induction audit had found independently. Raise to
+  error once a corpus is clean if you want it to gate.
+severity: warn
+applies-to:
+  glob: "documentation/references/**/*.md"
+checks:
+  - type: unregistered-uncertainty
+    obstacleWithinLines: 2