asciidoc-pubkit 1.0.3 → 1.2.0

data/docs/skill-commands.md

@@ -0,0 +1,136 @@
+# Skill registration commands
+
+These commands are available in pubkit **1.2.0 or later**. Install the gem or see
+[local checkout usage](installation.md#run-from-a-local-checkout) to run from source.
+
+Pubkit installs its bundled agent skills at a destination you choose. Commands
+use local package files only: they do not fetch arbitrary skills, invoke an AI,
+register an account, edit manuscripts or upgrade review sessions. Ruby 3.2 or
+later and pubkit's Ruby dependencies are required; MeCab is not required here.
+
+## List and install
+
+```sh
+asciidoc-pubkit skill list
+asciidoc-pubkit skill list --json
+asciidoc-pubkit skill install review-asciidoc-manuscript --agent codex
+```
+
+`list` describes the bundled skills. With `--json`, it also reports the
+available pubkit version and packaged files. The initial bundled skill is
+`review-asciidoc-manuscript`.
+`install NAME --dir PATH` creates `PATH/NAME`, copying the bundled SKILL.md and
+resources and recording their SHA-256 hashes in `.asciidoc-pubkit-skill.json`.
+Missing parent directories are created. Paths are caller-relative, so run from
+your manuscript directory or supply an absolute destination.
+
+Choose exactly one destination option for `install`, `status` and `upgrade`:
+
+| Option | Parent directory relative to the current working directory |
+| --- | --- |
+| `--agent codex` | `.agents/skills` |
+| `--agent claude` | `.claude/skills` |
+| `--dir PATH` | An explicit custom path (absolute paths are also accepted) |
+
+For Claude Code, for example:
+
+```sh
+asciidoc-pubkit skill install review-asciidoc-manuscript --agent claude
+asciidoc-pubkit skill status review-asciidoc-manuscript --agent claude
+asciidoc-pubkit skill upgrade review-asciidoc-manuscript --agent claude
+```
+
+Both agents receive the same [Agent Skills format](https://agentskills.io/specification).
+The specification defines skill contents, not their installation location.
+These project paths follow the [Codex documentation](https://learn.chatgpt.com/docs/build-skills)
+and [Claude Code documentation](https://code.claude.com/docs/en/skills).
+`--agent` selects a destination only; it does not invoke an agent, detect a
+running agent, change settings, or add agent-specific skill extensions. Run from
+the project directory where you want the skill installed; pubkit does not search
+for a repository root. `list` accepts neither destination option.
+
+For personal installation, use an explicit directory such as
+`--dir ~/.agents/skills` for Codex or `--dir ~/.claude/skills` for Claude Code.
+There is no default destination when neither option is supplied, and combining
+`--agent` with `--dir` is an error. Status and upgrade must select the same
+location used for installation. Skill discovery is owned by the agent; you can
+also ask it to read the installed SKILL.md explicitly, as shown in
+[skill integration](skill-integration.md).
+
+An existing destination, including an empty directory or manually copied skill,
+is not overwritten or adopted. Use another destination for a managed copy.
+Do not copy registration metadata onto a custom skill to bypass this check.
+Symlink paths and symlink skill content are rejected. File names and resources
+remain within the named skill directory; parent-level unrelated skills are kept.
+
+## Inspect registration
+
+```sh
+asciidoc-pubkit skill status review-asciidoc-manuscript --agent codex
+asciidoc-pubkit skill status review-asciidoc-manuscript --agent codex --json
+```
+
+Status is read-only and creates no directories. It compares installed file
+contents and inventory against registration hashes and the current package.
+Text output names changed files. JSON reports `name`, `destination`,
+`available_version`, `installed_version`, `state`, and file-name arrays
+`modified`, `missing`, `extra` and `updated`. `updated` identifies additions,
+removals or content changes in the available bundle; it is not a text diff.
+
+| State | Meaning |
+| --- | --- |
+| `current` | Registered files and version match the running pubkit bundle |
+| `update-available` | Untouched registered copy differs from the running bundle or version |
+| `modified` | Registered content was changed, removed or supplemented, including extra empty directories |
+| `not-installed` | The destination does not exist |
+| `unmanaged` | The destination exists without registration metadata |
+| `newer-installed` | A newer pubkit version owns the unchanged installed copy; downgrade is blocked |
+
+Malformed or unsupported metadata is an error, not an invitation to reset its
+hashes. Registration metadata is a local ownership record, not a cryptographic
+signature or proof that the skill was reviewed by an agent.
+
+## Upgrade an unchanged skill
+
+```sh
+# Update pubkit deliberately after a new release becomes available.
+gem update asciidoc-pubkit
+asciidoc-pubkit skill status review-asciidoc-manuscript --agent codex
+asciidoc-pubkit skill upgrade review-asciidoc-manuscript --agent codex
+```
+
+For a Bundler-managed project, update the selected gem and run these commands
+through `bundle exec`. `upgrade` uses the bundle in the pubkit invocation you
+actually run. It neither downloads a newer gem nor promises that this bundle is
+the newest upstream version. A changed source checkout can also supply updates
+at the same package version; file hashes identify those differences.
+
+Only `current` and `update-available` copies can be upgraded. Current copies are
+left unchanged. Locally changed, missing, unmanaged or newer-version copies are
+rejected; there is no `--force` option. Keep author-specific style and terminology
+in project instructions rather than editing the managed skill. To customize the
+skill itself, keep a separately named copy and merge changes manually.
+
+Installation and upgrade are serialized per parent directory using a temporary
+`.asciidoc-pubkit-skills.lock` directory. New files are staged before replacing
+the installed directory. A failed replacement restores the original; if restoring
+also fails, the error reports the preserved backup path. A process interrupted
+abruptly can leave a lock or staging directory. Check that no command is running
+and preserve any backup before removing a stale lock or retrying.
+
+Skill updates leave `manifest.json`, `document.json`, `findings.json` and
+`baseline/` in existing review sessions unchanged. Continue an existing review
+with its saved tool version and prompt. Start a different session to use newer
+criteria; a new baseline cannot prove preservation against an earlier one.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | List/install/upgrade succeeded, or status is `current` |
+| `1` | Status is another supported state; inspect its report |
+| `2` | Invalid arguments, bundle, path, registration or file operation |
+
+A status exit of 1 can mean an available update, not an installation failure.
+These commands do not interactively ask to replace content or automatically
+invoke an agent.
+
+[Skill integration tutorial](skill-integration.md) · [Back to README](../README.md)

data/docs/skill-integration.md

@@ -0,0 +1,190 @@
+# Integrate manuscript review into an agent skill
+
+Use `skill install` to register the bundled review workflow in your project.
+These registration commands require pubkit **1.2.0 or later**, as
+explained in [skill commands](skill-commands.md). The [CLI tutorial](agent-review-tutorial.md) covers individual
+scan, prompt and verify commands.
+
+A skill makes the same process reusable: the agent selects the manuscript,
+executes the commands, reads the generated prompt, edits within scope, verifies
+and records progress. Pubkit still performs parsing and preservation checks;
+it installs skill files without discovering them or launching a reviewer.
+
+## Responsibilities
+
+```mermaid
+flowchart TD
+    U["Author: assignment and edit authorization"] --> K["Agent reads the registered review skill"]
+    G["Local pubkit bundle"] --> T["skill install NAME --agent codex or claude"]
+    T --> K
+    I["Author instructions and optional review records"] --> K
+    K --> S["Agent runs pubkit scan"]
+    S --> B["Saved session and baseline"]
+    B --> P["Agent runs pubkit prompt"]
+    P --> R["Agent reads saved criteria and manuscript evidence"]
+    R --> E["Agent reviews or edits the assigned scope"]
+    E --> V["Agent runs pubkit verify"]
+    B --> V
+    V --> C["Agent records decisions, results and pending work"]
+    C --> N["Next assigned phase after successful verification"]
+```
+
+| Owner | Responsibility |
+| --- | --- |
+| Author and book instructions | Readers, style, technical evidence, assignment and publication decisions |
+| Review skill | Scope selection, phase order, tool invocation, resumption and progress recording |
+| Generated pubkit prompt | Criteria frozen at scanning, selected entries, candidates and edit permissions |
+| Codex or Claude reviewer | Evidence-based decisions, authorized edits and unresolved proposals |
+| Pubkit verification | Mechanical preservation against the saved baseline |
+
+Keep shared prose and heading criteria in pubkit instead of copying them into
+each skill. Skill instructions should explain when and how to use the tool,
+while book instructions retain book-specific terminology and technology versions.
+
+## 1. Register the review skill
+
+From your manuscript directory, list the bundled skills and install the review
+workflow for Codex in the current project:
+
+```sh
+asciidoc-pubkit skill list
+asciidoc-pubkit skill install review-asciidoc-manuscript --agent codex
+asciidoc-pubkit skill status review-asciidoc-manuscript --agent codex
+```
+
+If you already registered this skill while following the CLI tutorial, skip
+`install` and inspect it with `status`; registration does not overwrite an
+existing copy.
+
+The resulting layout is:
+
+```text
+manuscript-project/
+  book.adoc
+  AGENTS.md                 # Optional project instructions
+  .agents/skills/review-asciidoc-manuscript/
+    SKILL.md
+    .asciidoc-pubkit-skill.json
+```
+
+The registration file records the owning pubkit version and content hashes.
+Read the [bundled SKILL.md](../examples/skills/review-asciidoc-manuscript/SKILL.md)
+to understand its workflow. Leave the managed copy unchanged; keep author-specific
+scope, style and terminology in project instructions or the review request.
+
+For Claude Code, substitute `--agent claude` in install, status and upgrade;
+it selects `.claude/skills`. Both options install the same Agent Skills format.
+Use `--dir PATH` instead for a custom parent directory, including a personal
+installation. Do not combine it with `--agent`. Neither option changes agent
+settings or invokes an agent. See [destination options](skill-commands.md#list-and-install).
+
+The explicit file-reading requests below use the Codex path. For Claude Code,
+replace `.agents/skills/` with `.claude/skills/`.
+
+## 2. Ask the agent to use the registered skill
+
+Example request for either reviewer:
+
+```text
+Read .agents/skills/review-asciidoc-manuscript/SKILL.md and the project's
+instructions, if present. Review book.adoc in headings, prose and supported
+list phases. Use the author's requested style and terminology.
+Use a new pass named review-book-02, preserve previous baselines and unrelated
+edits and verify each phase before the next scan. Update an existing review
+record if available; otherwise save decisions alongside each session.
+Report applied changes, reviewed/pending IDs and coverage limits.
+```
+
+For outline diagnosis only:
+
+```text
+Read .agents/skills/review-asciidoc-manuscript/SKILL.md. Diagnose book.adoc's
+headings through parsed level 2 using a fresh review-toc-02 session and an outline
+prompt. Do not edit the manuscript. Record title/body agreement, reading order,
+keep/revise/needs-evidence decisions and separate structural proposals.
+```
+
+The agent checks the installed tool before using 1.1.0 options. A new session
+does not upgrade an old baseline or certify preservation against it.
+
+## 3. Commands the skill orchestrates
+
+For a heading-only assignment, the agent runs the following from the manuscript
+directory, reading the prompt and completing the assigned review between prompt
+and verify. Substitute unused pass names and the project's CLI invocation.
+
+```sh
+asciidoc-pubkit --version
+asciidoc-pubkit review scan --help
+asciidoc-pubkit review scan book.adoc --scope headings --lang ja \
+  --output .pubkit/review-book-02-headings --no-input
+asciidoc-pubkit review prompt .pubkit/review-book-02-headings --view outline \
+  --mode revise --output .pubkit/review-book-02-headings/prompt.md
+# Agent reads the prompt, records decisions and applies authorized title edits.
+asciidoc-pubkit review verify .pubkit/review-book-02-headings \
+  --output .pubkit/review-book-02-headings/verification-01.json
+```
+
+For a full review, proceed to fresh prose and list sessions only after the
+preceding phase is finished and verifies. The [CLI tutorial](agent-review-tutorial.md#4-review-prose-then-list-text)
+contains those command sequences. Do not scan all phases first: the later
+baseline must capture earlier authorized edits. A pending integrity or
+preservation failure blocks that phase boundary, not unrelated read-only work.
+
+Use generated criteria rather than a second writing prompt. Keep the session's
+four baseline artifacts immutable; adding prompt, decision and verification
+reports beside them is permitted. Existing output files cannot be overwritten.
+
+## 4. Check and upgrade the registered skill
+
+After deliberately updating the pubkit invocation used by your project:
+
+```sh
+asciidoc-pubkit skill status review-asciidoc-manuscript --agent codex --json
+asciidoc-pubkit skill upgrade review-asciidoc-manuscript --agent codex
+```
+
+`upgrade` installs the running package's bundle only when the registered copy is
+unchanged. `status` identifies locally modified, missing or extra files and the
+available bundle's changed files. A changed copy is kept, and an unmanaged
+manual copy is not adopted. Install to another directory to compare a managed
+copy with a custom workflow. See [skill commands](skill-commands.md) for states,
+exit codes and recovery behavior.
+
+Do not edit registration hashes to force an update. Skills and review sessions
+have separate lifecycles: updating the skill does not replace saved review
+criteria or baselines. Keep the original prompt and exact tool version for an
+ongoing session, or start a new pass in a different directory.
+
+## 5. Adapt the skill to your project
+
+Provide the book's entrypoint and the source files covered by the assignment.
+For a multi-file book, derive reading order from active includes rather than
+assuming a `chapters` directory or fixed filenames. A chapter-limited request
+uses the publication entrypoint with `--only`; a whole-book request uses that
+entrypoint without the filter. The [CLI tutorial](agent-review-tutorial.md#6-apply-the-workflow-to-your-own-book)
+shows an included-chapter example.
+
+The author supplies the intended readers, style, terminology and technical
+evidence. Read existing project instructions when available; a file named
+`AGENTS.md` and dedicated plan, structure or progress files are optional.
+Use the project's existing review records if available. Otherwise save a
+local decision report alongside each session, keeping the four baseline
+artifacts unchanged. Do not introduce a competing record into a project that
+already has one. Pubkit does not prescribe or validate report filenames.
+
+Select the project's installed invocation, such as `asciidoc-pubkit` or
+`bundle exec asciidoc-pubkit`. Record its version. Use the author's publishing
+attributes and base directory; do not rewrite include conventions merely to
+make a scan succeed. The example requires Japanese review support and MeCab
+with UTF-8 IPADIC by default. It does not enable review in other languages.
+
+Adapt checks to the actual project: inspect diffs, validate local references,
+and run existing lint or build commands when requested. No particular Make
+targets, EPUB tooling or publishing service are required by the skill. Keep
+mechanical preservation, editorial completion, book build checks and publication
+approval as separate recorded results. Applying the example does not authorize
+publishing the book or changing another project's files.
+
+[CLI tutorial](agent-review-tutorial.md) · [Review reference](review-workflow.md) ·
+[Back to README](../README.md)

data/docs/writing.md

@@ -18,6 +18,15 @@ book explicitly requires one. Sentence splitting and punctuation changes must
 retain the original relationships; these are contextual review instructions,
 not automatic semantic checks. Saved sessions retain the criteria from their scan.
 
+Sentence-ending review first identifies scope guides, actual operations,
+capabilities, checking procedures, and historical or future statements. Keep
+useful guidance and precise plain verbs; clarify vague judgment targets or
+comparison axes from passage evidence. Preserve negation strength: a definite
+difference is not interchangeable with insufficient evidence for equality.
+A noun-phrase heading policy does not apply to body sentences. These examples
+are contextual decisions, not new detector terms or replacement rules. See
+[Sentence-ending criteria](../data/writing/ja/criteria.md#review-sentence-endings-by-their-role).
+
 The criteria also preserve the comparison axis, completed changes,
 current behavior, future plans, and the distinction between event dates and
 observation or report dates. An unclear state term does not authorize deleting
@@ -25,13 +34,21 @@ its known action. Keep source-provided undecided or investigation status in the
 body; put reviewer doubts and questions in the separate report, without adding
 editing markers to the manuscript.
 
+The shared criteria also distinguish human roles from human-versus-AI
+comparisons. Terms such as `開発者`, `利用者`, `評価担当者`, and `文書の作成者`
+are evidence-based alternatives to `人`, not a replacement dictionary. Preserve
+general populations and established research concepts, and do not introduce
+new permissions or imply that different roles require different people.
+Heading criteria connect terminology changes with the section's body and
+separately proposed table, figure, and alternative-text synchronization.
+
 ```sh
 asciidoc-pubkit writing criteria --lang ja
 asciidoc-pubkit writing prompt --lang ja --output writing-prompt.md
 ```
 
 For example, `--lang en` exits with an unsupported-language error. No English
-review or writing criteria are shipped in 1.0.3.
+review or writing criteria are shipped in 1.2.0.
 
 For a small trial, use `examples/book.adoc` as the scan input. Its Japanese
 paragraphs deliberately contain review candidates; its code block must remain

data/examples/skills/review-asciidoc-manuscript/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: review-asciidoc-manuscript
+description: Review and revise an existing Japanese AsciiDoc manuscript with asciidoc-pubkit in separate verified heading, prose, and list sessions; use for proofreading or outline diagnosis, not new-book authoring.
+---
+
+# Review an AsciiDoc manuscript
+
+Read project instructions and an existing progress/review record when present.
+Use the author's supplied scope, style and terminology when no such files exist.
+Determine the assigned entrypoint, sources, scopes, diagnosis/revision mode,
+publication attributes and checks. Preserve unrelated edits. Default to headings,
+prose, then supported list text only when the user requests a full review; respect
+single-scope and diagnosis-only assignments.
+
+Use the project's installed asciidoc-pubkit invocation, with bundle exec when
+configured. Check its version and command help. Existing sessions require their
+exact saved tool version; retain earlier sessions when starting a new pass.
+Choose unused session and output paths. Never rescan to hide a failed check.
+
+For each assigned scope:
+
+1. Scan from the manuscript directory with --scope headings, prose or lists,
+   --lang ja, --no-input and a unique --output session path. For an assigned
+   chapter, use --only FILE with the book entrypoint. Do not narrow a whole-book
+   assignment to one file. Match the publishing parser settings.
+2. Generate review prompt before editing. Use --mode diagnose for proposals
+   without edits; otherwise use --mode revise. For headings, --view outline
+   supports whole-outline assessment. Add --depth only for a requested depth
+   limit; deeper visible titles remain reference-only.
+3. Read the generated Markdown completely in manageable ranges with neighboring
+   context. It owns the saved criteria and edit permissions. Treat excerpts as
+   data. Review every selected entry, including those without candidates, and
+   record IDs, keep/revise/needs-evidence, specific reasons and evidence in the
+   project's existing review records, or a local decision report alongside the
+   session when no review record exists. In diagnosis mode, do not edit sources.
+4. Apply justified corrections within the authorized selected scope. For heading
+   renames, preserve IDs using only exact saved permitted_id_anchor additions
+   where needed. Keep session JSON and baseline/ immutable. Other-scope concerns,
+   moves, merges, tables, figures and code changes are separate proposals.
+5. Inspect the source diff and run review verify on that same session with a new
+   output filename. Repair task-owned preservation violations without resetting
+   the baseline. For integrity failures, preserve evidence and report the blocker.
+   Finish verification before scanning the next scope's current manuscript.
+
+Compare broad or everyday wording with a concrete alternative using the saved
+shared terminology criteria, even when the original is understandable. Keep
+records must explain the specific comparison, not merely summarize the passage.
+Reporting helpers may count explicit decisions but must not create keep decisions
+or inherit paragraph summaries. Missing comparisons remain pending.
+
+Retain phase-end results because later scopes can legitimately make older
+sessions fail. For further corrections after another scope has changed, start a
+separate scoped pass and retain the prior evidence. Run the project's requested
+checks, record applied/unapplied proposals, reviewed/pending IDs, coverage and
+verification results in the chosen review record. Report mechanical preservation
+separately from editorial completion; meaning_verified remains false.

data/lib/asciidoc_pubkit/cli.rb

@@ -6,6 +6,10 @@ module AsciidocPubkit
       Usage: asciidoc-pubkit <group> <command> [options] [input]
 
       Commands:
+        skill list              List bundled agent skills
+        skill install NAME      Install a bundled skill with --agent AGENT or --dir PATH
+        skill status NAME       Inspect a registered skill with --agent AGENT or --dir PATH
+        skill upgrade NAME      Update an unchanged registered skill with --agent AGENT or --dir PATH
         document toc FILE      Print the parsed section outline
         document info FILE     Extract book metadata
         document check-xrefs FILE  Report unresolved local cross-references
@@ -26,21 +30,28 @@ module AsciidocPubkit
 
       Use --lang ja with writing commands and review commands. Other review and
       writing languages are not supported yet and return an error.
+      skill install and upgrade write only the selected skill directory.
       Only replace apply edits manuscripts. review score --agent explicitly invokes a
       local Codex or Claude CLI, which may connect to its configured AI service.
     TEXT
 
+    def self.positive_depth(value)
+      raise Error, 'Depth must be a positive integer.' unless value.match?(/\A[1-9][0-9]*\z/)
+      value.to_i
+    end
+
     def self.run(arguments, out: $stdout, err: $stderr, input: $stdin)
       args = arguments.dup
       if args == ['--version']
         out.puts VERSION
         return 0
       end
-      if args.empty? || args == ['--help'] || args == ['-h'] || %w[review writing replace document].any? { |group| args == [group, '--help'] }
+      if args.empty? || args == ['--help'] || args == ['-h'] || %w[review writing replace document skill].any? { |group| args == [group, '--help'] }
         out.puts HELP
         return 0
       end
       group, command = args.shift(2)
+      return SkillCommands.run(command, args, out: out, err: err) if group == 'skill'
       if group == 'document' && %w[toc info check-xrefs index].include?(command)
         return DocumentCommands.run(command, args, out: out, err: err)
       end
@@ -63,6 +74,7 @@ module AsciidocPubkit
           if command == 'scan'
             opts.on('--scope SCOPE', 'prose (default), headings, or lists; separate review sessions') { |v| options[:scope] = v }
             opts.on('--heading-rules FILE', 'Replace default heading rules with a YAML rule set') { |v| options[:heading_rules] = v }
+            opts.on('--depth N', 'Maximum section level; requires --scope headings') { |v| options[:depth] = positive_depth(v) }
             opts.on('-y', '--yes', 'Answer yes to replacement confirmation') { options[:yes] = true }
             opts.on('--no-input', 'Never prompt; fail on existing output unless --yes') { options[:no_input] = true }
           else
@@ -84,6 +96,7 @@ module AsciidocPubkit
           end
         elsif group == 'review' && command == 'prompt'
           opts.on('--mode MODE', 'revise (default) or diagnose') { |v| options[:mode] = v }
+          opts.on('--view VIEW', 'full (default) or outline; outline requires a heading session') { |v| options[:view] = v }
         end
         opts.on('-h', '--help', 'Show command help') { options[:help] = true }
       end
@@ -152,7 +165,7 @@ module AsciidocPubkit
         raise Error, "Requested language #{options[:language].inspect} does not match session language #{saved_language.inspect}."
       end
       if command == 'prompt'
-        output(session.prompt(options.fetch(:mode, 'revise')), options[:output], out)
+        output(session.prompt(options.fetch(:mode, 'revise'), view: options.fetch(:view, 'full')), options[:output], out)
         return 0
       end
       result = session.verify

data/lib/asciidoc_pubkit/document.rb

@@ -63,6 +63,14 @@ module AsciidocPubkit
                          'reason' => 'The source title is reused by multiple sections and cannot be edited independently.' }
           true
         end
+        if (depth = @settings['heading_depth'])
+          @headings.reject! do |heading|
+            next false unless heading['level'] > depth
+            @coverage << { 'context' => 'heading', 'file' => heading['file'], 'line' => heading['line'],
+                           'reason' => 'Outside the saved heading depth.', 'text' => heading['text'] }
+            true
+          end
+        end
         nodes.each { |node| collect(node) }
         if scope == 'lists'
           reused = @paragraphs.group_by { |p| [p['file'], p['line']] }.select { |_, group| group.length > 1 }
@@ -102,10 +110,11 @@ module AsciidocPubkit
     # Converted inline titles, attribute substitutions and old-style titles stay protected.
     def collect_heading(node, index)
       parent_index = @section_indexes[node.parent] if node.parent.context == :section
+      cursor = node.source_location
       @outline << { 'index' => index, 'parent_index' => parent_index,
-                    'level' => node.level, 'section_id' => node.id, 'text' => node.title }
+                    'level' => node.level, 'section_id' => node.id, 'text' => node.title,
+                    'file' => cursor&.file, 'line' => cursor&.lineno }
       return unless @settings.fetch('scope', 'prose') == 'headings'
-      cursor = node.source_location
       path, line = cursor && [cursor.file, cursor.lineno]
       match = @heading_lines[[path, line]]
       unless match && match[2] == node.title

data/lib/asciidoc_pubkit/document_commands.rb

@@ -21,9 +21,9 @@ module AsciidocPubkit
         end
         if command == 'toc'
           opts.on('--depth N', 'Maximum section level (positive integer)') do |v|
-            raise Error, 'Depth must be a positive integer.' unless v.match?(/\A[1-9][0-9]*\z/)
-            options[:depth] = v.to_i
+            options[:depth] = CLI.positive_depth(v)
           end
+          opts.on('--json', 'Output a structured outline with source locations') { options[:json] = true }
           opts.on('-n', '--numbered', 'Output outline numbers such as 1-2') { options[:numbered] = true }
         elsif command == 'index'
           opts.on('-t', '--title TITLE', 'Prepend an AsciiDoc index title') { |v| options[:title] = v }
@@ -112,6 +112,7 @@ module AsciidocPubkit
     end
 
     def toc(doc)
+      return JSON.pretty_generate(toc_outline(doc)) + "\n" if @options[:json]
       lines = []
       walk = lambda do |sections, prefix, nesting|
         sections.each_with_index do |section, index|
@@ -127,6 +128,35 @@ module AsciidocPubkit
       lines.empty? ? '' : lines.join("\n") + "\n"
     end
 
+    def toc_outline(doc)
+      entries = []
+      source_lines = {}
+      walk = lambda do |sections, prefix, nesting, parent_index|
+        sections.each_with_index do |section, sibling|
+          number = prefix + [sibling + 1]
+          next if @options[:depth] && section.level > @options[:depth]
+          cursor = section.source_location
+          source_title = nil
+          if cursor && cursor.file && File.file?(cursor.file)
+            lines = source_lines[cursor.file] ||= begin
+              check_source(cursor.file, File.realpath(doc.base_dir))
+              AsciidocPubkit.read_text(cursor.file).lines
+            end
+            line = lines[cursor.lineno - 1]
+            source_title = line&.match(/\A={1,6}[ \t]+(.*?)[ \t]*\r?\n?\z/)&.[](1)
+          end
+          index = entries.length
+          entries << { 'index' => index, 'parent_index' => parent_index,
+                       'level' => section.level, 'nesting' => nesting, 'number' => number.join('-'),
+                       'section_id' => section.id, 'title' => section.title,
+                       'file' => cursor&.file, 'line' => cursor&.lineno, 'source_title' => source_title }
+          walk.call(section.sections, number, nesting + 1, index)
+        end
+      end
+      walk.call(doc.sections, [], 0, nil)
+      { 'schema_version' => 1, 'entry' => doc.attr('docfile'), 'depth' => @options[:depth], 'headings' => entries }
+    end
+
     def index(directory)
       root = File.realpath(directory)
       raise Error, "Input is not a directory: #{directory}" unless File.directory?(root)

data/lib/asciidoc_pubkit/heading_rules.rb

@@ -52,6 +52,7 @@ module AsciidocPubkit
             next if settings['allows'].include?(term)
             text.to_enum(:scan, Regexp.new(Regexp.escape(term))).each do
               match = Regexp.last_match
+              next if term == '人' && !Rules.standalone_human?(text, match.begin(0))
               add(findings, heading, match.begin(0), term, rule, entry['question'])
             end
           end

data/lib/asciidoc_pubkit/rules.rb

@@ -113,6 +113,7 @@ module AsciidocPubkit
       tokens.each_with_index do |token, index|
         next if token['unknown'] || phrase_ranges.any? { |range| range.cover?(token['offset']) }
         lemma = token['lemma']
+        next if lemma == '人' && !standalone_human?(text, token['offset'])
         rule = nil
         finish_index = index
         compound = rules.fetch('compound_nouns').find do |term|
@@ -185,6 +186,7 @@ module AsciidocPubkit
         surfaces.each do |surface|
           text.to_enum(:scan, Regexp.new(Regexp.escape(surface))).each do
             match = Regexp.last_match
+            next if surface == '人' && !standalone_human?(text, match.begin(0))
             next if contextual.any? { |start, finish, _, candidate_rule, *_| start == match.begin(0) && finish == match.end(0) && candidate_rule == rule }
             candidates << [match.begin(0), match.end(0), surface, rule, question]
           end
@@ -200,6 +202,18 @@ module AsciidocPubkit
       end
     end
 
+    # Exclude compound words, identifiers and counts in both tokenizer modes.
+    # Hiragana context such as その人 or 人による remains a review cue.
+    def self.standalone_human?(text, offset)
+      compound = /[\p{Han}\p{N}\p{Latin}\p{Katakana}_]/
+      previous = offset.positive? ? text[offset - 1] : nil
+      following = text[offset + 1]
+      return false if previous == 'ー' || previous&.match?(compound)
+      return true if text[(offset + 1)..].start_with?('向け')
+
+      following != 'ー' && !following&.match?(compound)
+    end
+
     def self.find_term(findings, paragraph, text, term, rule, severity, question)
       text.to_enum(:scan, Regexp.new(Regexp.escape(term))).each do
         match = Regexp.last_match